Agent Cost & UsageSDK Integration

SDK Integration

Use the Mavvrik SDK when the agent application can load a Mavvrik library at startup. The SDK observes supported AI libraries and records their model usage, timing, status, trace relationships, and pricing inputs without replacing existing provider or framework calls.

Mavvrik provides SDKs for Python and JavaScript / TypeScript.

Set up the SDK

1. Register an Agent.

2. Confirm the application stack in Supported Agentic Stacks.

3. Install the SDK and required instrumentation.

4. Initialize Mavvrik before supported provider or framework calls begin.

5. Run one known test request.

6. Verify the request in Home → Agentic → Cost and Home → Agentic → Sessions.

7. Add business context or metered usage only when required.

What Mavvrik captures automatically

For supported AI calls, Mavvrik records telemetry exposed by the library, including:

• provider and model;

• input/output token or equivalent usage quantities;

• cached and reasoning token fields where exposed;

• request duration;

• success/failure and error information;

• trace relationships;

• one-way prompt/response fingerprints;

• pricing inputs used by Mavvrik to calculate cost.

Prompt and response text is not required for standard cost reporting and is not sent by default.

Framework instrumentation can capture framework-level activity together with supported model calls beneath it, so the execution trace shows which agent step produced the model usage.

What the SDK instruments

The SDK attaches only to supported integrations. It is not a general APM agent and does not instrument arbitrary application functions, databases, file I/O, message queues, or internal business logic.

The SDK can instrument these scopes:

The language quickstarts initialize with wrappers={"include": ["genai"]} for a minimal AI-cost setup. Add vectordb when retrieval operations should also appear in the execution trace.

Use Track Metered Usage for paid resources such as OCR, external APIs, document processing, storage, or other per-unit services that are not priced by supported automatic instrumentation.

HTTP instrumentation

HTTP instrumentation is opt-in. In Python, HTTP visibility is limited to supported httpx instrumentation when explicitly enabled.

Request and response bodies are not read. Captured HTTP telemetry is operational metadata such as host, method, status, and duration.

Exclude hosts that must not be observed:

export MVK_HTTP_EXCLUSIONS='["internal-billing.corp","patient-records.internal","hr-payroll.internal"]'

Do not enable HTTP instrumentation when supported provider/framework instrumentation already supplies the required cost and execution data.

Confirm stack compatibility

Use Supported Agentic Stacks to check supported providers, frameworks, vector databases, web frameworks, and runtimes.

Third-party dependency compatibility can depend on the installed library version. If a provider or framework version is not recognized by the installed Mavvrik SDK, that integration can be skipped and logged rather than instrumented.

After upgrading an AI dependency, confirm that the integration loads successfully:

export MVK_LOG_LEVEL=DEBUG

Add business context

Use Add Business Context to attribute captured usage and cost to a customer, user, session, application, use case, request, region, or other reporting dimension.

Track metered non-LLM usage

Use Track Metered Usage when the workflow consumes a paid resource that Mavvrik cannot price automatically.

Metered usage supplies the metric, quantity, unit, and optional rate. Add a signal only when the operation should also appear as a named step in the execution trace.

Inspect telemetry locally

export MVK_EXPORTER_TYPE=console
export MVK_EXPORTER_FORMAT=json

Use DEBUG logging to confirm which integrations loaded successfully:

export MVK_LOG_LEVEL=DEBUG

Network requirements

Direct SDK export sends telemetry over HTTPS to:

ingest.mavvrik.ai:443

Reliability behavior

Mavvrik instrumentation is designed to fail open so telemetry problems do not become application failures.

Key runtime behaviors:

• telemetry export is asynchronous;

• records use a bounded in-memory buffer of approximately 10 MB;

• telemetry can be dropped when the buffer is full rather than allowing memory usage to grow without bound;

• transient delivery failures are retried with backoff;

• persistent failures can spill telemetry batches to local disk for later retry;

• ingest unavailability can cause telemetry-data loss or delay without blocking the application request path.

For serverless and short-lived processes, use the documented flush/shutdown behavior before process exit.

Disable SDK tracking

export MVK_ENABLED=false

Continue with a language quickstart

• Register an Agent

• Supported Agentic Stacks

• Python SDK Quickstart

• JavaScript / TypeScript SDK Quickstart