Setting Up SigNoz for Inkeep Agent Framework Observability

SigNoz gives you distributed tracing and observability for the Inkeep Agent Framework. This guide walks you through two setup paths: connecting to SigNoz Cloud, or running SigNoz locally with Docker.

Before you begin

Make sure you have the Inkeep Agent Framework installed and your development environment set up before following either path below.

Option 1: SigNoz Cloud

1. Sign up at signoz.io and create a project.
2. From your project settings, collect the following values:
   • API Key
   • Ingestion Key
   • SigNoz URL (includes your region, e.g. https://us.signoz.cloud)

3. Add the following to your .env file:

   SIGNOZ_URL=https://<your-region>.signoz.cloud
   SIGNOZ_API_KEY=<your-api-key>
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.us.signoz.cloud:443/v1/traces
   OTEL_EXPORTER_OTLP_TRACES_HEADERS="signoz-ingestion-key=<your-ingestion-key>"

 

When creating your API key, set the expiration to No Expiry. A Viewer role is sufficient for observability — you do not need admin access.

Option 2: Local Docker setup

Running SigNoz locally spins up SigNoz, an OpenTelemetry Collector, Jaeger, and Nango via Docker Compose. You can do this automatically with a single command, or manually if you prefer more control.

Automated Manual

If you have already run pnpm setup-dev, run the following command to start all optional services:

pnpm setup-dev:optional

This starts SigNoz, the OTEL Collector, Jaeger, and Nango via Docker Compose. It also auto-registers an admin account and writes the required environment variables to your .env file.

1. Clone the optional services repository into .optional-services/:

   git clone https://github.com/inkeep/agents-optional-local-dev .optional-services/

2. Start SigNoz with Docker Compose:

   docker compose --profile signoz up -d

3. Add the following to your .env file:

   SIGNOZ_URL=http://localhost:3080
   SIGNOZ_API_KEY=<your-signoz-api-key>
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
   OTEL_SERVICE_NAME=inkeep-agents

Local UI access

• SigNoz UI: http://localhost:3080
• Jaeger UI: http://localhost:16686

Utility commands

Use these commands to manage your local optional services:

Command	What it does
pnpm dev	Restart the dev server
pnpm optional:status	Check the health of optional services
pnpm optional:stop	Stop all optional services
pnpm optional:reset	Reset optional services to a clean state