Overview

The payi_instrument() function is the entry point for Pay-i's automatic instrumentation. Call it once at application startup to intercept GenAI provider calls and route telemetry to Pay-i. This page is a configuration reference — for usage patterns and getting started, see Day 1: Basic Instrumentation.

Function Signature

from payi.lib.instrument import payi_instrument

payi_instrument(
    payi=None,
    instruments=None,
    log_prompt_and_response=True,
    config=None,
    logger=None,
)

All parameters are keyword-only. Calling payi_instrument() more than once is a no-op — only the first call takes effect.

Top-Level Parameters

Instrument Values

When you pass a set of strings to instruments, only the matching providers are instrumented. Use the PayiCategories class for readable, typo-proof values:

from payi.lib.helpers import PayiCategories

# Instrument only OpenAI and Anthropic
payi_instrument(instruments={PayiCategories.openai, PayiCategories.anthropic})

PayiInstrumentConfig

The config parameter accepts a PayiInstrumentConfig dictionary. Settings fall into two groups: behavior settings that control how instrumentation works, and global context defaults that set initial values for the context.

Behavior Settings

Global Context Defaults

These values populate the initial context frame when global_instrumentation = True. They can be overridden per-request by @track, track_context, or extra_headers.

payi_instrument(
    config={
        "use_case_name": "customer_support_bot",
        "user_id": "user5",
        "limit_ids": ["global_budget"],
        "request_properties": {"environment": "production"},
    }
)

Host Mappings

Maps hostnames to Pay-i categories for correct pricing. This is needed when you use a provider's client SDK to send requests to a host other than the provider's own — for example, using the OpenAI client to communicate with open-weight models hosted on Databricks or a custom inference endpoint. Without a host mapping, Pay-i will use the default category value associated with the client which will result in an unknown_model.

The key is a hostname string or httpx.URL. The value is a PayiInstrumentHostMappingConfig dictionary.

payi_instrument(
    config={
        "host_mappings": {
            "my-workspace.cloud.databricks.com": {"price_as_category": "system.databricks.azure"},
        }
    }
)

Offline Instrumentation

Writes telemetry packets to a local JSON file instead of sending them to Pay-i. The file is written when the process exits. This is useful for testing, debugging, or air-gapped environments.

payi_instrument(
    config={
        "offline_instrumentation": {"file_name": "telemetry_capture.json"}
    }
)

When offline instrumentation is enabled, no Pay-i client is required.

Ingest Retry

Controls retry behavior when ingest calls to the Pay-i service fail due to transient connection errors. There are two retry layers: inline retries that happen synchronously before the call returns, and a background retry queue that re-delivers failed packets asynchronously.

payi_instrument(
    config={
        "ingest_retry": {
            "max_inline_retries": 2,
            "inline_retry_initial_delay": 1.0,
            "queue_enabled": True,
            "queue_max_size": 100,
        }
    }
)

OpenAI Config

Configuration for the OpenAI provider instrumentation.

payi_instrument(
    config={
        "openai_config": {
            "model_mappings": [
                {"model": "my-gpt4-deployment", "price_as_resource": "gpt-4"},
            ]
        }
    }
)

Anthropic Config

Configuration for the Anthropic provider instrumentation.

payi_instrument(
    config={
        "anthropic_config": {
            "model_mappings": [
                {"model": "my-claude-deployment", "price_as_resource": "claude-sonnet-4-20250514"},
            ]
        }
    }
)

AWS Bedrock Config

Configuration for the AWS Bedrock provider instrumentation.

Model Mappings

Model mappings tell Pay-i how to price requests when the model name or deployment name doesn't directly correspond to a known Pay-i resource. Each mapping is a dictionary with these fields:

At least one setting (price_as_category, price_as_resource, or resource_scope) must be specified.

payi_instrument(
    config={
        "aws_config": {
            "model_mappings": [
                {
                    "model": "arn:aws:bedrock:us-east-1::foundation-model/my-custom-model",
                    "price_as_category": "system.aws.bedrock",
                    "price_as_resource": "anthropic.claude-3-sonnet",
                    "resource_scope": "region.us-east-1",
                },
            ]
        }
    }
)

Model Config

Per-model configuration, keyed by model name.