September 2026 release is live Read More
Breadcrumbs

Troubleshooting Agent Data

Troubleshooting Agent Data

Use the symptom that matches the observed problem and verify one layer of the data path at a time.

No SDK data appears in Mavvrik

Check in this order:

  1. Agent identity — confirm MVK_TENANT_ID, MVK_AGENT_ID, and MVK_API_KEY match the values in the agent's Connect step.

  2. Startup order — confirm mvk.instrument() runs before the provider or framework is imported or used.

  3. Instrumentation package — confirm the required Python extra or JavaScript @mvk/instr-* package is installed.

  4. Wrapper configuration — confirm the required integration is enabled.

  5. SDK enabled — confirm MVK_ENABLED is not false.

  6. Supported activity — run one known model request after instrumentation starts.

  7. Network — direct-export workloads must reach ingest.mavvrik.ai over HTTPS port 443.

  8. Processing time — allow up to 10 minutes for the first processed result to appear.

Debug logging

Bash
export MVK_LOG_LEVEL=DEBUG

Inspect telemetry locally

Bash
export MVK_EXPORTER_TYPE=console
export MVK_EXPORTER_FORMAT=json

If the expected AI operation appears locally, continue checking credentials, network access, telemetry export, or processing in Mavvrik.

One provider or framework is missing

Check for:

  • provider or framework imported before Mavvrik initialization;

  • missing instrumentation package or Python extra;

  • installed library version not recognized by the installed SDK;

  • MVK_WRAPPERS restricting instrumentation to another set of integrations.

See Supported Agentic Stacks.

Model activity appears but token usage is missing

Mavvrik records usage fields exposed by the underlying provider or library.

Check whether:

  • the source response contains input/output or equivalent usage fields;

  • a streaming response was consumed to completion;

  • the provider mode exposes cached, reasoning, or other specialized usage fields.

Do not add metered usage to replace missing automatically captured model-token fields. This can create duplicate cost.

Model activity appears but cost is missing

Confirm:

  1. model identity is present;

  2. input/output or applicable usage quantities are present;

  3. Mavvrik has a matching default model price, or a published Configure LLM Pricing rule applies;

  4. the pricing rule is effective for the matching usage.

For OpenRouter or other routing paths, verify the model/provider fields returned by the source.

Agent name changed but Agent ID did not

This is expected. Agent Name is a display value and can change. Agent ID is the stable SDK attribution identity and cannot be changed after registration.

See Register an Agent.

Authentication returns 401 or 403

Check:

  • the API key is current and has not been rotated;

  • the API key belongs to the tenant being sent;

  • no whitespace or trailing newline was added when reading the key from a secret or file;

  • tenant ID and agent ID match the Connect values.

Do not send an API key to Mavvrik support when collecting diagnostics.

Troubleshoot business context

Session, user, or customer fields are missing

The context must start before the downstream activity executes.

Incorrect:

Python
response = call_model()
with mvk.context(session_id="session-123"):
    return response

Correct:

Python
with mvk.context(session_id="session-123"):
    response = call_model()
    return response

Context is missing from background work

When work moves to another thread, process, queue, or job, set the required context again inside the worker.

Nested context contains the wrong value

An inner context overrides the same field or tag from an outer context.

Tags are missing

For Python, confirm:

  • no more than 10 custom tags are attached to a span;

  • keys use lowercase [a-z0-9._-] and are no longer than 64 characters;

  • values are no longer than 256 characters.

Avoid high-cardinality tag values such as timestamps, request UUIDs, document IDs, or raw user content.

Troubleshoot metered usage

Metered usage is missing

Confirm the executed code path calls add_metered_usage() / addMeteredUsage().

Python uses metric_kind; JavaScript / TypeScript uses metricKind.

Metered usage appears but cost is missing

Confirm the usage contains:

  • metric name;

  • quantity;

  • unit;

  • rate_per_unit.

Python
mvk.add_metered_usage([
    {
        "metric_kind": "document.pages",
        "quantity": 42,
        "uom": "page",
        "metadata": {"rate_per_unit": 0.0015},
    }
])

A named operation is missing from the trace

Metered usage records consumption. It does not require a named trace step.

If the operation should appear as a distinct step in Home → Agentic → Sessions, wrap it with @mvk.signal() / @mvkSignal() or create_signal() / createSignal().

For TypeScript createSignal(), ensure signal.end() always runs:

TypeScript
const signal = createSignal(...);
try {
  await doWork();
} finally {
  signal.end();
}

If a signal appears but an expected field is missing, verify the exact API field name. Python and TypeScript signal APIs have field-name differences, and unsupported parameters can be ignored without failing the application.

Total cost is higher than expected

Check for duplicate cost:

  • do not add metered usage for a model call Mavvrik already prices automatically;

  • confirm the same paid operation is not recorded more than once;

  • confirm nested signals represent different operations rather than duplicate boundaries around the same charge.

Troubleshoot LLM pricing

Published LLM pricing rule does not apply

Confirm:

  1. effective date;

  2. scope;

  3. provider/platform;

  4. model;

  5. pricing unit;

  6. whether a more specific rule takes precedence.

Agent(s) > Team(s) > Workspace > Tenant

Draft cards do not affect cost calculation.

Troubleshoot LiteLLM

No LiteLLM data appears

Confirm:

YAML
litellm_settings:
  callbacks: ["otel"]

Restart the proxy after configuration changes.

Confirm:

Bash
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_RESOURCE_ATTRIBUTES=mvk.connection_id=<connection-id>

LiteLLM data appears as Unattributed

Add an agent ID through supported LiteLLM request metadata or:

x-litellm-agent-id: support-agent

LiteLLM sessions do not group 

x-litellm-session-id: session-456

Troubleshoot Langfuse

Connection is Active but no agents are discovered

Confirm:

  • at least one Agent metadata key is configured;

  • fresh Langfuse traces contain that field;

  • the field value is a string;

  • case and whitespace match exactly.

Python
metadata={"agent_id": "support-agent"}

Agents are discovered but no data is collected

Connect the discovered agent to start collecting its data.

Older Langfuse traces do not appear

The first collection window is 24 hours. Generate fresh traffic and wait for the next 10-minute polling cycle.

Troubleshoot n8n

No n8n startup instrumentation message appears

Confirm:

Bash
NODE_OPTIONS=--import @mavvrikai/n8n-sdk/register
MVK_ENABLED=true

For Docker, rebuild or restart after installing the SDK or changing environment variables.

Bash
MVK_LOG_LEVEL=debug
MVK_PRINT_SUMMARY=human

n8n activity appears without business context

Place the Edit Fields (Set) or Code node immediately after the trigger. The n8n SDK captures workflow business context once per execution; fields added later are not used as execution-level context.

n8n queue-mode context is inconsistent

Set static MVK_BUSINESS_CONTEXT on the main, worker, and webhook processes.

Troubleshoot serverless and short-lived processes

A short-lived process can exit before buffered telemetry is exported.

Python:

Python
from mvk_sdk import force_flush

try:
    result = do_work()
finally:
    force_flush()

JavaScript / TypeScript:

TypeScript
import { flushWithBudget } from '@mavvrikai/sdk/serverless';

try {
  return await doWork();
} finally {
  await flushWithBudget(1000);
}

For scripts and batch jobs, shut down the SDK before process exit.

TypeScript decorators do not run

Decorator forms require decorator support in the TypeScript project configuration. If decorators are not enabled, use function equivalents such as withMvkContext() and manually created signal APIs.

Information to provide to Mavvrik support

Provide:

  • integration type;

  • agent or connection name and ID;

  • approximate test-request time;

  • session ID, if configured;

  • SDK/package version;

  • AI provider/framework names and versions;

  • relevant DEBUG startup lines;

  • whether local console telemetry contains the expected operation.

Prompt/response text and API keys are not required to diagnose standard cost-ingestion issues.