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: Create one billable metric per provider you want to bill on. Paygentic rejects spans whose eventType has no matching metric with 422 and suppresses them 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:
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:
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 exporter drops the event. 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:
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). The exporter rejects events with an unknown type with 422 and temporarily suppresses them.
  • 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