Observability · Guide

Examples

Every example in the repository is a single standalone file, runnable as written. Start with the one that matches your framework — or with the manual agent, which is the template for a framework nobody has integrated yet. Four of them run offline and cost nothing.

They live in examples/ in the source repository. Clone it, or copy the file you want.

Two environment variables

export COGNIPEER_API_KEY="cpeer_…"                        # Settings → API Tokens, with tracing enabled
export COGNIPEER_BASE_URL="https://console.acme.internal" # self-hosted only; host root, no /api path

Every example checks for what it needs up front and exits with a clear message, rather than failing halfway through a run.

Python

python examples/python/manual_agent.py

Example	Shows	Needs	Cost
manual_agent.py	@observe, trace(), and recording a model call by hand with tokens and a tool menu	nothing	Free, offline
langgraph_agent.py	interrupt and resume as two sessions on one thread; interrupts recorded as pauses, not failures	[langgraph]	Free, offline
langchain_agent.py	a real tool-calling agent, with tool schemas captured per model call	[langchain], langchain-openai, OPENAI_API_KEY	Calls OpenAI
openai_agents_example.py	install_openai_agents_tracing() and RunConfig(group_id=…) for thread grouping	[openai-agents], OPENAI_API_KEY	Calls OpenAI
claude_agent_example.py	trace_query as a drop-in for query; tool_use and tool_result merged into one event	[claude-agent-sdk], Claude Code CLI, ANTHROPIC_API_KEY	Calls Anthropic
otel_crewai.py	the "any framework" path — CognipeerSpanExporter inside a TracerProvider	[otel], crewai, openinference-instrumentation-crewai, OPENAI_API_KEY	Calls OpenAI

Bracketed names are extras: pip install "cognipeer-observability[langgraph]".

TypeScript

npx tsx examples/js/manual-agent.ts

Example	Shows	Needs	Cost
manual-agent.ts	observe(), trace(), and recording a model call by hand	nothing	Free, offline
langchain-agent.ts	a real tool-calling agent with CognipeerCallbackHandler	@langchain/*, OPENAI_API_KEY	Calls OpenAI
openai-agents.ts	installOpenAIAgentsTracing() and groupId	@openai/agents, OPENAI_API_KEY	Calls OpenAI
vercel-ai.ts	the native telemetry integration and the portable middleware route, side by side	ai, @ai-sdk/openai, OPENAI_API_KEY	Calls OpenAI

n8n

The bridge needs no files and works on n8n Cloud — run it after a test execution to verify the wiring end to end:

npx --package=@cognipeer/observability cognipeer-n8n \
  --n8n-url https://n8n.acme.com --n8n-api-key "$N8N_API_KEY" \
  --api-key "$COGNIPEER_API_KEY" --once

The examples/n8n/ directory also carries a docker-compose.yml that runs the bridge alongside n8n, and cognipeer-hook.js for the push-based external-hook route on self-hosted installs. The three routes and their tradeoffs are compared in the n8n guide.

Keep the run data

Set EXECUTIONS_DATA_SAVE_ON_SUCCESS=all on n8n. With its pruning defaults the execution payloads are stripped, and the traces arrive empty — n8n's execution run data is the only place its AI Agent nodes record prompts, completions, token usage and tool results.

Nothing showing up?

Run again with COGNIPEER_DEBUG=1. It logs every request the exporter makes and every failure it swallowed.

The usual cause in a script is a missing flush(): exports are asynchronous, and a short-lived process can exit before the last one lands. Every example here calls it. For the rest, Troubleshooting lists the five things that actually go wrong, in order of likelihood.