CognethicsDevelopers

Observability & Tracing

Every mission and agent instance is instrumented with OpenTelemetry traces and cost telemetry. Query cost and token data programmatically via REST; the delegation tree is a console feature.

Overview

Cognethics instruments:

  1. Cost telemetry — per-mission cost timelines and per-agent token distribution, including cache-read visibility
  2. OpenTelemetry traces — trace_id, span_id, and parent_span_id on every span, correlated across a mission and its delegated child agents
  3. Memory and governance analytics — organization-wide memory usage by tier and per-mission governance metrics
  4. Observability export — stream cost and audit events to your own destination

All data is per-tenant scoped and queryable in real time.

Mission Records

List mission observability records:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-tenant.cognethics.com/api/agents/missions/observability/"

Fetch a single mission's record:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-tenant.cognethics.com/api/agents/missions/observability/sess_550e8400/"

Cost Telemetry

Cost timeline

Fetch cumulative spend over time for a mission session:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-tenant.cognethics.com/api/agents/costs/timeline/?session_id=sess_550e8400&interval=hour"

interval is hour or day. Response:

{
  "session_id": "sess_550e8400e29b41d4a716446655440000",
  "interval": "hour",
  "data_points": [
    {
      "period": "2026-05-21T15:00:00Z",
      "cost_usd": 2.30,
      "input_tokens": 8200,
      "output_tokens": 1800,
      "cache_read_tokens": 12000,
      "agent_count": 2,
      "cumulative_cost_usd": 2.30
    },
    {
      "period": "2026-05-21T16:00:00Z",
      "cost_usd": 3.80,
      "input_tokens": 9800,
      "output_tokens": 2100,
      "cache_read_tokens": 15400,
      "agent_count": 2,
      "cumulative_cost_usd": 6.10
    }
  ]
}

Token distribution

Fetch token usage by model and by agent for a mission session:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-tenant.cognethics.com/api/agents/costs/token-distribution/?session_id=sess_550e8400"

Response:

{
  "session_id": "sess_550e8400e29b41d4a716446655440000",
  "total_tokens": 65000,
  "by_model": [
    { "model": "<model>", "input_tokens": 45000, "output_tokens": 8500, "cache_read_tokens": 12000 }
  ],
  "by_agent": [
    {
      "id": "agt_550e8400e29b41d4a716446655440000",
      "instance_name": "Chief Auditor",
      "current_model": "<model>",
      "input_tokens": 25000,
      "output_tokens": 3200,
      "cache_read_tokens": 2000,
      "total_tokens": 30200,
      "total_cost_usd": 15.20,
      "share_pct": 58.4
    },
    {
      "id": "agt_550e8400e29b41d4a716446655440001",
      "instance_name": "Invoice Analyzer",
      "current_model": "<model>",
      "input_tokens": 12000,
      "output_tokens": 3100,
      "cache_read_tokens": 10000,
      "total_tokens": 25100,
      "total_cost_usd": 7.50,
      "share_pct": 28.9
    }
  ]
}

Cache visibility. cache_read_tokens is reported per model and per agent — tokens reused from a previously cached prompt prefix. A higher cache-read count relative to input tokens means lower cost and latency.

Distributed Tracing

Every mission is instrumented with OpenTelemetry spans. Each span carries:

  • trace_id — correlated across the entire mission and every delegated child agent
  • span_id — unique within the trace
  • parent_span_id — links to the caller's span

The delegation tree — which agent spawned which, and how each completed — is built from the agent spawn graph and is a console feature: open a mission in the operator console to view it. It is not a REST endpoint called with a bearer token.

Memory Analytics

Fetch organization-wide persistent-memory usage:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-tenant.cognethics.com/api/agents/pj/analytics/memory/"

Returns organization-wide totals by memory tier, average relevance score, and the average number of memories per persona.

Governance Analytics

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-tenant.cognethics.com/api/agents/pj/analytics/governance/"

Observability Export

Stream cost and audit events to your own destination:

  • GET/POST /api/v1/observability/export/destinations/ — list and register export destinations
  • POST /api/v1/observability/export/destinations/{id}/enable/ — enable a destination
  • POST /api/v1/observability/export/destinations/{id}/disable/ — disable a destination
  • GET /api/v1/observability/export/destinations/{id}/health/ — destination health status
  • POST /api/v1/observability/export/destinations/{id}/test/ — send a test event
  • POST /api/v1/observability/export/destinations/validate-endpoint/ — validate an endpoint before registering it
  • POST /api/v1/observability/export/dead-letters/{id}/replay/ — replay an event that failed delivery

Use Cases

Optimize spending

  1. Fetch the cost timeline for a mission session
  2. Identify the period(s) with the steepest spend
  3. Fetch the token distribution and compare cache_read_tokens against input_tokens per agent — a low ratio means prompt caching needs tuning

Audit a delegation chain

  1. Open the mission in the operator console to view the delegation tree
  2. Verify each child agent completed successfully
  3. Cross-check governance analytics for any escalations along the way

API Reference

List / get mission records

GET /api/agents/missions/observability/ — list

GET /api/agents/missions/observability/<session_id>/ — detail

Fetch cost timeline

GET /api/agents/costs/timeline/?session_id=<uuid>&interval=hour|day

Fetch token distribution

GET /api/agents/costs/token-distribution/?session_id=<uuid>

Fetch memory analytics

GET /api/agents/pj/analytics/memory/

Organization-wide totals by tier, average relevance, and average memories per persona.

Fetch governance analytics

GET /api/agents/pj/analytics/governance/

Observability export

GET/POST /api/v1/observability/export/destinations/ · POST .../enable/ · POST .../disable/ · GET .../health/ · POST .../test/ · POST .../validate-endpoint/ · POST /api/v1/observability/export/dead-letters/{id}/replay/

Next Steps

  • Monitor a mission — poll the cost timeline and token distribution for a session
  • Optimize spend — use token distribution to find low cache-read agents and reduce redundant calls
  • Audit governance decisions — cross-check governance analytics with the audit log
  • Export to your own systems — register a destination under Observability Export

Questions? See the reference or reach our support team through the contact form.