OpenTelemetry Replicate Instrumentation

Warnings

• breaking Starting from versions around 0.54.0, `openllmetry` (and thus `opentelemetry-instrumentation-replicate`) began conforming to the OpenTelemetry Generative AI Semantic Conventions (GenAI SemConv) version 0.5.0. This significantly changes the names and structure of attributes on spans related to LLM calls. If you have custom dashboards, alerts, or processing pipelines based on older attribute names, these will likely break.
  Fix: Review the OpenTelemetry GenAI Semantic Conventions (https://opentelemetry.io/docs/specs/semconv/llm/llm-spans/) and update your OTLP consumers, dashboards, and queries to use the new attribute names. For example, 'llm.request.type' might become 'gen_ai.request.type'.
• gotcha This instrumentation only tracks calls made via the `replicate` Python client. It does not automatically capture Replicate API calls made through other means (e.g., direct HTTP requests, other SDKs). Ensure all Replicate interactions you wish to trace go through the instrumented `replicate` package.
  Fix: Always use the `replicate` Python client after `ReplicateInstrumentor().instrument()` has been called if you want to capture traces.
• gotcha The `opentelemetry-instrumentation-replicate` package requires the `replicate` library to be installed separately. It is not bundled as a direct dependency to allow for flexible dependency management.
  Fix: Ensure `pip install replicate` is run in your environment alongside the instrumentation package. A full install command is `pip install opentelemetry-instrumentation-replicate replicate opentelemetry-sdk`.
• gotcha For `replicate.predictions.create` to function correctly and avoid API errors, a valid `REPLICATE_API_TOKEN` environment variable must be set. The instrumentation itself does not handle authentication, only tracing successful or failed API calls.
  Fix: Set the `REPLICATE_API_TOKEN` environment variable with your actual Replicate API key before making any Replicate client calls.

Install

• pip install opentelemetry-instrumentation-replicate replicate opentelemetry-sdk Install with Replicate client and OTel SDK

Imports

• ReplicateInstrumentor

  from opentelemetry.instrumentation.replicate import ReplicateInstrumentor

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter, instrument the Replicate client, and then make calls to Replicate. The console will display the generated traces for the Replicate operations.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.replicate import ReplicateInstrumentor

# 1. Setup OpenTelemetry SDK (for demonstration, using ConsoleSpanExporter)
resource = Resource.create({"service.name": "replicate-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 2. Instrument Replicate
ReplicateInstrumentor().instrument()

# 3. Use Replicate client (ensure REPLICATE_API_TOKEN is set in environment)
# For local testing, you might set a dummy value, but real use requires a valid token.
os.environ["REPLICATE_API_TOKEN"] = os.environ.get("REPLICATE_API_TOKEN", "r8_DUMMY_TOKEN_FOR_TESTING")

import replicate

# Example: List models (this operation will be traced)
models = replicate.models.list()
print(f"Found {len(models)} Replicate models. First one: {models[0].id if models else 'N/A'}")

# Example: Create a prediction (this operation will be traced)
# Note: This requires a valid Replicate API token and potentially an actual model ID/version
try:
    model_version_id = "stability-ai/sdxl:39edb22c277335607b222fbc6e31ddadead4ad77a102713f01b34e53d5d71c1f"
    prediction = replicate.predictions.create(
        version=model_version_id,
        input={"prompt": "a photo of an astronaut riding a horse on mars"}
    )
    print(f"Replicate prediction created: {prediction.id}")
except Exception as e:
    print(f"Could not create Replicate prediction (check API token and model ID): {e}")

print("Traces should be visible in the console.")