How dakshrjain737/ai-agent-observatory-backend works
AI Agent Observatory is a secured Spring REST backend for collecting agent traces and spans, grouping them into sessions, and querying telemetry. The main workflow routes SDK ingestion through API-key security and controllers into trace/span services, which resolve session and parent/child relationships and persist through JPA repositories; human users register and access protected APIs with JWT authentication. The README also documents analytics, but its implementation was not sampled, so its wiring is left unspecified.
Main entry points: SpanServiceImpl.java Span service · TraceServiceImpl.java Trace service · TraceRepository.java Trace repository · SessionRepository.java Session repository
Components 23
Security
- API-key filter
src/main/java/com/backend_agent_obs/agent/auth/filter/ApiKeyHashAuthenticationFilter.java - JWT filters
src/main/java/com/backend_agent_obs/agent/auth/filter/JWTAuthenticationFilter.java - Security config
src/main/java/com/backend_agent_obs/agent/config/SecurityConfig.java
REST API
- Trace API
src/main/java/com/backend_agent_obs/agent/controller/TraceController.java - Span API
src/main/java/com/backend_agent_obs/agent/controller/SpanController.java - User API
src/main/java/com/backend_agent_obs/agent/controller/UserController.java - Analytics API
src/main/java/com/backend_agent_obs/agent/controller/AnalyticsController.java
Telemetry Services
- Trace service
src/main/java/com/backend_agent_obs/agent/services/serviceImpl/TraceServiceImpl.java - Span service
src/main/java/com/backend_agent_obs/agent/services/serviceImpl/SpanServiceImpl.java - User service
src/main/java/com/backend_agent_obs/agent/services/serviceImpl/UserServiceImpl.java - Analytics service
src/main/java/com/backend_agent_obs/agent/services/serviceImpl/AnalyticServiceImpl.java - Trace mapping
src/main/java/com/backend_agent_obs/agent/mappers/TraceMapperImpl.java - Span mapping
src/main/java/com/backend_agent_obs/agent/mappers/SpanMapperImpl.java - Analytics DTOs
src/main/java/com/backend_agent_obs/agent/dto/entityDto/TraceAnalyticsDto.java
Persistence
- Trace repository
src/main/java/com/backend_agent_obs/agent/repo/TraceRepository.java - Span repository
src/main/java/com/backend_agent_obs/agent/repo/SpanRepository.java - Session repository
src/main/java/com/backend_agent_obs/agent/repo/SessionRepository.java - User repository
src/main/java/com/backend_agent_obs/agent/repo/UserRepository.java - Telemetry entities
src/main/java/com/backend_agent_obs/agent/entities/entity/Trace.java - User and roles
src/main/java/com/backend_agent_obs/agent/entities/entity/User.java
Other components
- Agent SDK
- Human user
- PostgreSQL / H2
Connections 28
- Agent SDK → API-key filter: sends credentials
- API-key filter → Security config: authenticates
- Human user → JWT filters: sends credentials
- JWT filters → Security config: validates tokens
- Agent SDK → Trace API: submits traces
- Agent SDK → Span API: submits spans
- Human user → User API: registers users
- Trace API → Trace service: delegates requests
- Span API → Span service: delegates requests
- User API → User service: delegates requests
- Analytics API → Analytics service: requests metrics
- Trace service → Trace repository: reads and writes
- Trace service → Session repository: resolves sessions
- Trace service → Trace mapping: maps traces
- Span service → Trace repository: resolves traces
- Span service → Session repository: resolves sessions
- Span service → Span repository: reads spans
- Span service → Span mapping: maps spans
- User service → User repository: reads and writes
- Trace repository → PostgreSQL / H2: persists telemetry
- Span repository → PostgreSQL / H2: persists spans
- Session repository → PostgreSQL / H2: persists sessions
- User repository → PostgreSQL / H2: persists accounts
- Trace repository → Telemetry entities: stores
- Span repository → Telemetry entities: stores
- Session repository → Telemetry entities: stores
- User repository → User and roles: stores
- Analytics service → Analytics DTOs: produces metrics