{"id":2638,"library":"opentelemetry-instrumentation-milvus","title":"OpenTelemetry Milvus Instrumentation","description":"This library provides client-side instrumentation for the Milvus vector database within the OpenTelemetry ecosystem. It enables automatic tracing of interactions with Milvus, allowing developers to monitor performance, debug distributed systems, and gain observability into their AI applications. Part of the OpenLLMetry project, it adheres to OpenTelemetry standards and is actively maintained with a frequent release cadence, as seen by multiple updates in recent months.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-milvus","tags":["opentelemetry","milvus","instrumentation","tracing","vector database","observability","llm","genai"],"install":[{"cmd":"pip install opentelemetry-instrumentation-milvus","lang":"bash","label":"Install library"},{"cmd":"pip install pymilvus opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-grpc","lang":"bash","label":"Required dependencies for full tracing setup"}],"dependencies":[{"reason":"Official Milvus Python client library that is instrumented.","package":"pymilvus","optional":false},{"reason":"Core OpenTelemetry SDK for Python, essential for trace management and export.","package":"opentelemetry-sdk","optional":false},{"reason":"Exports telemetry data in OTLP format to a collector.","package":"opentelemetry-exporter-otlp","optional":false},{"reason":"Milvus client communicates via gRPC; this provides automatic gRPC call tracing.","package":"opentelemetry-instrumentation-grpc","optional":false}],"imports":[{"symbol":"MilvusInstrumentor","correct":"from opentelemetry.instrumentation.milvus import MilvusInstrumentor"}],"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 BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.instrumentation.grpc import GrpcInstrumentorClient\n\n# IMPORTANT: Instrument Milvus BEFORE importing pymilvus\nfrom opentelemetry.instrumentation.milvus import MilvusInstrumentor\nMilvusInstrumentor().instrument()\n\n# Configure OpenTelemetry (replace with your actual collector endpoint)\nos.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4317')\nos.environ['OTEL_SERVICE_NAME'] = os.environ.get('OTEL_SERVICE_NAME', 'milvus-client-app')\n\nresource = Resource.create({\n    \"service.name\": os.environ['OTEL_SERVICE_NAME'],\n    \"application\": \"milvus-otel-test\"\n})\n\ntrace.set_tracer_provider(\n    TracerProvider(resource=resource)\n)\n\notlp_exporter = OTLPSpanExporter()\nspan_processor = BatchSpanProcessor(otlp_exporter)\ntrace.get_tracer_provider().add_span_processor(span_processor)\n\n# Also instrument gRPC client explicitly for broader gRPC tracing\ngrpc_client_instrumentor = GrpcInstrumentorClient()\ngrpc_client_instrumentor.instrument()\n\n# Now import pymilvus\nfrom pymilvus import Collection, connections\n\n# Connect to Milvus (assuming a local Milvus instance)\nconnections.connect(\"default\", host=\"localhost\", port=\"19530\")\n\n# Perform a simple Milvus operation to generate a trace\ncollection_name = \"hello_milvus_otel\"\nif collection_name in connections.list_collections():\n    Collection(collection_name).drop()\n\nprint(f\"Milvus client instrumented. Check your OTLP collector/Jaeger at {os.environ['OTEL_EXPORTER_OTLP_ENDPOINT']}\")","lang":"python","description":"This quickstart demonstrates how to set up OpenTelemetry tracing for a Python application interacting with Milvus. It initializes the OpenTelemetry SDK with an OTLP exporter, instruments the Milvus client using `MilvusInstrumentor`, and then performs a basic Milvus operation. Ensure an OpenTelemetry Collector or Jaeger is running and accessible at the specified `OTEL_EXPORTER_OTLP_ENDPOINT` to receive traces. The `MilvusInstrumentor().instrument()` call should happen before importing `pymilvus`."},"warnings":[{"fix":"Ensure `from opentelemetry.instrumentation.milvus import MilvusInstrumentor` and `MilvusInstrumentor().instrument()` are executed early in your application's lifecycle, prior to any `import pymilvus` statements.","message":"It is critical to initialize the OpenTelemetry instrumentation for Milvus (e.g., `MilvusInstrumentor().instrument()`) *before* importing the `pymilvus` library. Failure to do so may result in gRPC calls not being properly traced.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to Milvus documentation for server-side OpenTelemetry configuration. Configure `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_SERVICE_NAME` environment variables (or equivalent SDK configuration) to point to your trace collector.","message":"This instrumentation primarily traces client-side interactions. For end-to-end observability, ensure your Milvus server instance is also configured to emit OpenTelemetry traces (Milvus 2.3.0+ supports this) and that an OpenTelemetry Collector or Jaeger is running to receive all telemetry data.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Stay informed about OpenTelemetry semantic convention updates, particularly for `gen_ai.*` attributes. Review generated traces after upgrading to ensure compatibility with your observability backend and custom tooling.","message":"OpenTelemetry semantic conventions, especially in rapidly evolving areas like Generative AI (which OpenLLMetry targets), can change between versions. While the instrumentation API might remain stable, the names or structure of emitted span attributes could change, potentially breaking dashboards or alerts relying on older conventions.","severity":"breaking","affected_versions":"0.53.0 onwards (due to GenAI semconv focus)"},{"fix":"Apply instrumentation selectively within your application code or use environment variables like `OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES` (or language-specific equivalents) to prevent unwanted instrumentation.","message":"High CPU usage or unexpected behavior can occur if OpenTelemetry auto-instrumentation is enabled globally (e.g., via system-wide environment variables) and impacts unintended processes. This is a general risk with broad auto-instrumentation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}