Observability
Cognipeer Observability
An MIT-licensed tracing library for the agent you already built. Two lines make it observable — prompts, completions, tool calls, token usage, cost and latency — with no proxy, no base-URL swap, and no change to how your agent calls its models.
- Packages
@cognipeer/observability·cognipeer-observability - Languages TypeScript · Python 3.9+
- Licence MIT
The library is one monorepo publishing two packages that share a version number and a changelog: @cognipeer/observability on npm and cognipeer-observability on PyPI. Both map their framework's telemetry onto one ingest contract and post it to Cognipeer Console, where it becomes the run timeline, threads, cost attribution and evaluation datasets.
import cognipeer_observability as cognipeer
from cognipeer_observability.langchain import CognipeerCallbackHandler
cognipeer.init(api_key="cpeer_…", agent={"name": "support-bot"})
agent.invoke(state, config={"callbacks": [CognipeerCallbackHandler()]})import { init } from '@cognipeer/observability';
import { CognipeerCallbackHandler } from '@cognipeer/observability/langchain';
init({ apiKey: 'cpeer_…', agent: { name: 'support-bot' } });
await agent.invoke(state, { callbacks: [new CognipeerCallbackHandler()] });Getting started
Install the package, configure it, and produce a first trace in either language without a framework.
JavaScript & TypeScript
Subpath exports, optional peer dependencies, runtime support, flushing, the bundled CLI.
Python
Extras, module map, lazy framework imports, the decorator's sync, async and generator forms.
Examples
Runnable per-framework examples, what each one needs, and which ones cost money to run.
API reference
Every exported symbol, the init() options, the session primitive and its span methods.
Release notes
One changelog for both packages — what shipped in 0.1.0 and 0.2.0.
Where this section fits
This section documents the library: what to install, what it exports, how it behaves in your process. It does not repeat the per-framework wiring.
Each framework has one guide, and it lives on the Console side — with the Console screens, the ingest contract and the troubleshooting that go with it — so the two cannot drift:
| Framework | Python | TypeScript | Seam | Guide |
|---|---|---|---|---|
| LangChain | yes | yes | Callback handler, 0.1 to 1.x | LangChain |
| LangGraph | yes | yes | Same handler, plus thread and interrupt handling | LangGraph |
| OpenAI Agents SDK | yes | yes | Tracing processor | OpenAI Agents SDK |
| Claude Agent SDK | yes | yes | Message-stream tracer | Claude Agent SDK |
| Vercel AI SDK | — | yes | Telemetry integration or model middleware | Vercel AI SDK |
| n8n | — | yes | Execution bridge or external hook | n8n |
| Anything OpenTelemetry | yes | yes | Span exporter | OpenTelemetry |
| Anything else | yes | yes | observe / trace and the session API | Manual instrumentation |
Not on the list? If it emits OpenTelemetry spans — natively or through an OpenInference or OpenLLMetry instrumentor, as most 2026-era agent frameworks do — the OTLP route already covers it. That is what makes CrewAI, LlamaIndex, Pydantic AI, Google ADK, AWS Strands, Semantic Kernel, smolagents, Haystack and DSPy work with no bespoke integration.
What the package promises
These are properties the test suite checks, not aspirations — they are why it is safe to put in front of a production agent.
It never breaks the traced app
Every export path swallows its own failures and reports them through onError / on_error. A missing API key disables the exporter and warns once; it does not raise.
It never blocks it either
Exports run on a background daemon thread in Python and a promise chain in JavaScript. No integration awaits network I/O on a framework's hot path.
No dependency surprises
The core is standard-library only in both languages. Framework code is behind a subpath export or a lazy import, so installing it cannot move your lock file.
Secrets and blobs stay put
API-key-shaped strings are redacted by pattern, base64 data URLs are stripped, and section content is capped before anything is sent.
One more, worth stating on its own because it changes how you read a trace: absent is not zero. When a framework cannot report something — token usage on a streaming call without usage opt-in, tool schemas on a chat-completions path — the field is omitted rather than defaulted. A zero would silently under-report spend; an absent value shows up as unknown and can be chased.
Where the data lands
Every integration is a mapping onto one model — sessions containing events containing sections — and that contract is documented once, in Data Model. Once traces arrive, everything Console already does with its own agents applies:
- Tracing — the run timeline, with prompts, completions, tool arguments and results, nested by parent and child.
- Threads — several runs grouped into one conversation by
threadId. - Cost — trace-derived tokens priced against Model Hub or your external pricing catalogue, reported as
source: tracing. - Evaluation — datasets built from real traced runs and replayed against other models.
Next
- Getting started — install, configure, first trace
- Quickstart — the same thing end to end against a real framework
- Contributing — adding a framework integration
- Source on GitHub