{"id":2644,"library":"opentelemetry-instrumentation-replicate","title":"OpenTelemetry Replicate Instrumentation","description":"OpenTelemetry Replicate instrumentation provides automatic tracing for applications using the Replicate Python client, allowing developers to monitor and observe AI/ML model inferences. It is part of the `openllmetry` project and is currently at version 0.58.0, with frequent releases to keep up with OpenTelemetry semantic conventions and new LLM integrations, typically on a weekly or bi-weekly cadence.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-replicate","tags":["opentelemetry","observability","instrumentation","replicate","llm","ai","tracing","openllmetry"],"install":[{"cmd":"pip install opentelemetry-instrumentation-replicate replicate opentelemetry-sdk","lang":"bash","label":"Install with Replicate client and OTel SDK"}],"dependencies":[{"reason":"The library instruments the Replicate Python client.","package":"replicate","optional":false},{"reason":"Core OpenTelemetry API for defining traces.","package":"opentelemetry-api","optional":false},{"reason":"Required for configuring and exporting OpenTelemetry traces.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"ReplicateInstrumentor","correct":"from opentelemetry.instrumentation.replicate import ReplicateInstrumentor"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.replicate import ReplicateInstrumentor\n\n# 1. Setup OpenTelemetry SDK (for demonstration, using ConsoleSpanExporter)\nresource = Resource.create({\"service.name\": \"replicate-app\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Replicate\nReplicateInstrumentor().instrument()\n\n# 3. Use Replicate client (ensure REPLICATE_API_TOKEN is set in environment)\n# For local testing, you might set a dummy value, but real use requires a valid token.\nos.environ[\"REPLICATE_API_TOKEN\"] = os.environ.get(\"REPLICATE_API_TOKEN\", \"r8_DUMMY_TOKEN_FOR_TESTING\")\n\nimport replicate\n\n# Example: List models (this operation will be traced)\nmodels = replicate.models.list()\nprint(f\"Found {len(models)} Replicate models. First one: {models[0].id if models else 'N/A'}\")\n\n# Example: Create a prediction (this operation will be traced)\n# Note: This requires a valid Replicate API token and potentially an actual model ID/version\ntry:\n    model_version_id = \"stability-ai/sdxl:39edb22c277335607b222fbc6e31ddadead4ad77a102713f01b34e53d5d71c1f\"\n    prediction = replicate.predictions.create(\n        version=model_version_id,\n        input={\"prompt\": \"a photo of an astronaut riding a horse on mars\"}\n    )\n    print(f\"Replicate prediction created: {prediction.id}\")\nexcept Exception as e:\n    print(f\"Could not create Replicate prediction (check API token and model ID): {e}\")\n\nprint(\"Traces should be visible in the console.\")","lang":"python","description":"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."},"warnings":[{"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'.","message":"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.","severity":"breaking","affected_versions":">=0.54.0"},{"fix":"Always use the `replicate` Python client after `ReplicateInstrumentor().instrument()` has been called if you want to capture traces.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Set the `REPLICATE_API_TOKEN` environment variable with your actual Replicate API key before making any Replicate client calls.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}