Overview
This guide walks you through setting up monitoring and observability for Inkeep using OpenTelemetry and exporting traces to SigNoz. With this integration, you can observe the performance of various models, capture request/response details, and track system-level metrics in SigNoz, giving you real-time visibility into latency, error rates, and usage trends for your Inkeep applications.
Instrumenting Inkeep agents in your AI applications with telemetry ensures full observability across your agent workflows, making it easier to debug issues, optimize performance, and understand user interactions. By leveraging SigNoz, you can analyze correlated traces in dashboards, configure alerts, and gain actionable insights to continuously improve reliability, responsiveness, and user experience.
Prerequisites
Before getting started, ensure you have the following installed on your system:
- A SigNoz Cloud accountwith an active ingestion key orSelf Hosted SigNoz instance - Node.js version 22 or higher
- Docker
- pnpm version 10 or higher
You can verify by running:
node --version
pnpm --version
docker --version
Monitoring Inkeep
For more information on getting started with Inkeep, visit the Inkeep Quick Start Guide. To learn more about setting up traces in Inkeep and sending them to SigNoz, see the Inkeep Traces Documentation.
Step 1: Create a new agents project
Run the Inkeep quickstart script on a target folder:
npx @inkeep/create-agents my-agents
Navigate to the folder
cd my-agents
Open the folder using your coding editor. To open with Cursor, you can run cursor .
Step 2: Save Your SigNoz Credentials
You'll need to collect three pieces of information from your SigNoz dashboard:
API Key:
- Go to Settings → Service Accounts and create a new service account. - In the Overview tab, assign a role —Viewer is sufficient for observability. - Go to the Keys tab and clickAdd Key. - Set the expiration field to "No Expiry" to prevent the key from expiring.
- Copy the generated API key.
See Service Accounts for full details.
Ingestion Key:
- Navigate to Settings → Ingestion Settings - Set the expiration field to "No Expiry" to prevent the key from expiring
- Copy the ingestion key
SigNoz URL:
- Copy the URL from your browser's address bar
- It will look like:
https://<your-organization>.signoz.cloud
Step 3: Configure Your Root .env File
SIGNOZ_URL=https://<your-organization>.signoz.cloud
SIGNOZ_API_KEY=<your-signoz-api-key>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.<region>.signoz.cloud:443/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=signoz-ingestion-key=<your-ingestion-key>
<region>
: YourSigNoz Cloud region- Replace
<your-organization>
with your SigNoz Cloud instance name - Replace
<your-signoz-api-key>
with your SigNoz API Key. <your-ingestion-key>
: Your SigNozingestion key
SIGNOZ_URL=<your-local-signoz-instance>
SIGNOZ_API_KEY=<your-signoz-api-key>
- Replace
<your-local-signoz-instance>
with the localhost and port you are running SigNoz on. For example:http://localhost:8080
- Replace
<your-signoz-api-key>
with your SigNoz API Key.
Step 4: Run the setup script
Ensure Docker Desktop (or Docker daemon) is running before running the setup script.
pnpm setup-dev
Or if you are using a cloud database, you can skip the docker database startup by running:
pnpm setup-dev --skip-docker
Make sure your DATABASE_URL environment variable is configured for your cloud database.
Step 5: Launch the dev environment
pnpm dev
The Visual Builder will auto-open at http://localhost:3000.
View Traces in SigNoz
Your Inkeep agents usage should now automatically emit traces.
You should be able to view traces in Signoz Cloud under the traces tab:
When you click on a trace in SigNoz, you'll see a detailed view of the trace, including all associated spans, along with their events and attributes.
Troubleshooting
If you don't see your telemetry data:
Verify network connectivity- Ensure your application can reach SigNoz ingestion endpoints** Check ingestion key**- Verify your SigNoz ingestion key is correct** Wait for data**- OpenTelemetry batches data before sending, so wait 10-30 seconds after making API calls
Next Steps
You can also check out our custom Inkeep dashboard here which provides specialized visualizations for monitoring your Inkeep usage in applications. The dashboard includes pre-built charts specifically tailored for LLM usage, along with import instructions to get started quickly.
Additional resources:
- Set up alertsfor high latency or error rates - Learn more about querying traces - Explore log correlation