Docs

Documentation

How Nozzle works

Nozzle is an AI conversation-intelligence layer on top of SigNoz. Your agents emit OpenTelemetry gen_ai traces; Nozzle reads them from SigNoz, reconstructs conversations, classifies each with an LLM, and surfaces business insight — then writes its findings back into SigNoz. SigNoz is the observability layer; Nozzle is the semantic layer on top.

The pipeline

From raw agent spans to analyzed conversations and back — one continuous loop.

AI Agentsemit gen_ai spans
SigNozingest + store (OTLP)
Pollerv5 query API · 60s
Reconstructspans → conversations
LLM Analyzeintent · outcome · sentiment
Postgresconversations + analyses
DashboardsAstro UI

Self-observing loop: Nozzle writes verdicts back to SigNoz as correlated logs, emits its own metrics, and self-instruments its pipeline as traces — so the analyzer is observed by the very system it reads from.

Three OpenTelemetry signals

Nozzle uses all three OTel signals — the semantic layer rides in as span, log, and metric attributes.

Traces
read + write
  • Read agent gen_ai / OpenInference spans to reconstruct conversations
  • Derive tool latency (P50/P90/P99) and discover agents
  • Emit nozzle-backend spans (poll, analyze, chat) with gen_ai.* attrs
Logs
write
  • Each analysis verdict written back as an OTLP log
  • Correlated to the originating trace via trace/span context
  • Filterable in SigNoz by nozzle.intent, nozzle.outcome, …
Metrics
write
  • conversations.analyzed counter (intent / outcome / sentiment)
  • frustration.score + llm.duration histograms
  • llm.tokens counter — native SigNoz dashboards & alerts

Architecture

Two systems on a shared Docker network: the SigNoz stack, and Nozzle's own services.

Nozzle
Frontend
Astro + React islands
Backend API
FastAPI
Worker / Beat
Celery — poll & analyze
Postgres
conversations + analyses
OTLP / query
SigNoz
Ingester
OTLP :4318
ClickHouse
telemetry store
Query API
v5 query_range
UI
traces · logs · metrics

SigNoz integration

Query API
POST /api/v5/query_range, authenticated with the SIGNOZ-API-KEY header (not a bearer token).
Self-adapting fields
selectFields are filtered against /api/v1/fields/keys, so an attribute SigNoz has never ingested never 400s the query.
Write-back correlation
The verdict log's trace/span context is set from the source trace, so it lands on that trace in SigNoz.
Trace deep-links
Every reconstructed conversation links straight to its raw trace waterfall in the SigNoz UI.
Self-hosted or Cloud
Same OTel data — only the OTLP endpoint and the signoz-ingestion-key header differ for SigNoz Cloud.
GenAI conventions
Model-level fields follow gen_ai.* so SigNoz's derived fields recognize them.

Dashboards

Every panel is a Query Builder group-by over the semantics attached to your telemetry.

Overview
Conversations, events, resolution rate, intents, outcomes, trends.
Conversations
Explore reconstructed sessions; jump to the raw SigNoz trace.
Intents
Intent activity with a suggested → active → rejected curation flow.
Failures
Failure taxonomy distribution and per-reason drill-downs.
Customer Insights
Sentiment, frustration trend, and most-frustrated conversations.
Experiments
A/B compare agent variants on resolution and frustration.
Signals
Nozzle observing itself — the three OTel signals it emits & reads.
Tool Calls
Real tool-span latency percentiles from SigNoz durations.
Agents
Every service emitting traces, with span counts and watch state.
Studio
Turn docs/URLs/repos into an embeddable RAG agent that self-observes.

Configuration

Core environment variables (backend). Local and Cloud differ only in endpoint and auth.

SIGNOZ_QUERY_URLSigNoz query API base (read-back).
SIGNOZ_AUTH_TOKENService-account key, sent as the SIGNOZ-API-KEY header.
SIGNOZ_OTLP_ENDPOINT / INGESTION_URLOTLP export target — local :4318 or Cloud ingest URL.
INGESTION_KEYSigNoz Cloud ingestion key (sent as signoz-ingestion-key).
SIGNOZ_URLBrowser-reachable SigNoz UI base for trace deep-links.
SIGNOZ_SERVICE_NAMESComma-separated services the poller ingests.
CHAT_API_BASE / CHAT_MODEL / NVIDIA_API_KEYLLM endpoint for analysis (NVIDIA NIM).