Skip to main content
Monocle ships with a Paygentic span exporter that streams inference traces into your Paygentic account as CloudEvents. Once configured, Monocle’s traces feed your billable metrics directly — no separate instrumentation for billing. This guide covers the Paygentic-side setup. It assumes you already have Monocle installed and instrumenting your application.

​
Before you begin

​
Step 1: Define a Product and Billable Metric

In the Paygentic dashboard, create a product (for example, “Monocle Agent”) and a billable metric that matches the Monocle span you want to bill on. The Paygentic exporter derives the event type from the span’s entity.1.type attribute, prefixed with ai.. For example, an OpenAI chat completion (entity.1.type = "inference.openai") arrives at Paygentic with type = "ai.inference.openai". Map Monocle spans to billable-metric fields as follows:
FieldValue for MonocleExample
eventTypeai. + the Monocle entity typeai.inference.openai
valuePropertyJSONPath into the span’s metadata event$.total_tokens
groupByOptional dimensions you care about{ "model": "$.model_name" }
Create one billable metric per provider you want to bill on. Spans whose eventType has no matching metric are rejected with 422 and suppressed for an hour.
When you use a framework like LangChain or LlamaIndex, the event type still reflects the underlying provider — a LangChain ChatOpenAI call emits ai.inference.openai, a ChatAnthropic call emits ai.inference.anthropic, and so on. Unknown or unmapped LLM clients fall back to ai.inference.generic.
The data payload contains the attributes from the span’s metadata event (plus span_id, trace_id, and name). Common metadata fields across Monocle’s provider integrations include total_tokens, completion_tokens, prompt_tokens, and model_name. See Meter Events for the full list of aggregation options and JSONPath rules.
Monocle spans can also feed a cost metric alongside your billable metric, so the same event drives both customer billing and internal margin tracking.

​
Step 2: Enable the Paygentic Exporter

Configure the exporter via environment variables: 
export PAYGENTIC_API_KEY=sk_live_YOUR_API_KEY
Sandbox keys are prefixed sk_test_ and live keys sk_live_. When targeting the sandbox, also set PAYGENTIC_SANDBOX=true so events are routed to api.sandbox.paygentic.io. See Environments for details. Then add the paygentic exporter to your Monocle setup call: 
from monocle_apptrace.instrumentor import setup_monocle_telemetry

setup_monocle_telemetry(
    workflow_name="my-app",
    monocle_exporters_list="paygentic",
)
Event data should now flow into the Meters section of the Paygentic dashboard. Use this view to confirm the integration before moving on.
By default the exporter only exports inference spans — other Monocle span types are filtered out. The event source field defaults to "monocle"; override it per-app with PAYGENTIC_SOURCE=my-app.

​
Step 3: Attach Subscriptions via Trace Scopes

The exporter sets each event’s subject from a Monocle trace scope. It checks subscriptionId first, then falls back to customerId. If neither scope is set on the span, the event is dropped. Create a customer, subscribe them to a plan with a price on your Monocle metric, then tag traces with the subscription id before your instrumented workload runs: 
from monocle_apptrace.instrumentation.common.instrumentor import monocle_trace_scope

with monocle_trace_scope("subscriptionId", "sub_demo_123"):
    # your instrumented workload
    ...
See Customer Lifecycle for the full subscription activation flow.

​
Troubleshooting

  • Events aren’t showing up in the Meters view. Confirm your billable metric’s eventType matches the ai.-prefixed type the exporter emits (e.g. ai.inference.openai, not inference.openai). Events with an unknown type are rejected with 422 and temporarily suppressed by the exporter.
  • No subject resolved errors in application logs. The span has no subscriptionId or customerId scope — wrap the traced call in monocle_trace_scope(...).
  • Sandbox key with live endpoint (or vice versa). Set PAYGENTIC_SANDBOX=true when using an sk_test_ key.

​
Next steps