{"record":{"id":"3c2771c621a3880a","repo":"vllm-project/vllm","slug":"opentelemetry-is-not-available-unable-to-configur","errorCode":null,"errorMessage":"OpenTelemetry is not available. Unable to configure 'otlp_traces_endpoint'. Ensure OpenTelemetry packages are installed. Original error:\n{otel_import_error_traceback}","messagePattern":"OpenTelemetry is not available\\. Unable to configure 'otlp_traces_endpoint'\\. Ensure OpenTelemetry packages are installed\\. Original error:\n(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/observability.py","lineNumber":135,"sourceCode":"        hash_str = safe_hash(str(factors).encode(), usedforsecurity=False).hexdigest()\n        return hash_str\n\n    @field_validator(\"show_hidden_metrics_for_version\")\n    @classmethod\n    def _validate_show_hidden_metrics_for_version(cls, value: str | None) -> str | None:\n        if value is not None:\n            # Raises an exception if the string is not a valid version.\n            parse(value)\n        return value\n\n    @field_validator(\"otlp_traces_endpoint\")\n    @classmethod\n    def _validate_otlp_traces_endpoint(cls, value: str | None) -> str | None:\n        if value is not None:\n            from vllm.tracing import is_tracing_available, otel_import_error_traceback\n\n            if not is_tracing_available():\n                raise ValueError(\n                    \"OpenTelemetry is not available. Unable to configure \"\n                    \"'otlp_traces_endpoint'. Ensure OpenTelemetry packages are \"\n                    f\"installed. Original error:\\n{otel_import_error_traceback}\"\n                )\n        return value\n\n    @field_validator(\"collect_detailed_traces\")\n    @classmethod\n    def _validate_collect_detailed_traces(\n        cls, value: list[DetailedTraceModules] | None\n    ) -> list[DetailedTraceModules] | None:\n        \"\"\"Handle the legacy case where users might provide a comma-separated\n        string instead of a list of strings.\"\"\"\n        if value is not None and len(value) == 1 and \",\" in value[0]:\n            value = cast(list[DetailedTraceModules], value[0].split(\",\"))\n        return value\n\n    @model_validator(mode=\"after\")","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/observability.py#L117-L153","documentation":"ObservabilityConfig's field validator for otlp_traces_endpoint imports vllm.tracing helpers and checks is_tracing_available(). If the OpenTelemetry packages could not be imported, setting --otlp-traces-endpoint is rejected with the original import traceback appended, because OTLP export cannot function without them.","triggerScenarios":"Passing --otlp-traces-endpoint http://collector:4317 in an environment where vllm.tracing's OTel import failed — e.g. opentelemetry-sdk / opentelemetry-exporter-otlp not installed, or an incompatible/broken OTel version on sys.path.","commonSituations":"Minimal docker images or slim venvs that omit the optional tracing extras; upgrading vLLM without reinstalling otel packages; a half-broken OTel install where a submodule import raises.","solutions":["Install the OTel extras, e.g. uv pip install -r requirements/observability.txt or opentelemetry-sdk opentelemetry-exporter-otlp (match the versions vllm.tracing imports).","Re-check with python -c \"from vllm.tracing import is_tracing_available; print(is_tracing_available())\" — the traceback field of this error tells you exactly which import failed.","If tracing is optional in your deployment, drop --otlp-traces-endpoint until the packages are present."],"exampleFix":"# before\nvllm serve model --otlp-traces-endpoint http://otel:4317  # otel not installed -> ValueError\n\n# after\nuv pip install opentelemetry-sdk opentelemetry-exporter-otlp\nvllm serve model --otlp-traces-endpoint http://otel:4317","handlingStrategy":"validation","validationCode":"from vllm.tracing import is_tracing_available\n\ndef require_otel(endpoint: str | None) -> None:\n    if endpoint and not is_tracing_available():\n        raise SystemExit(\"Install opentelemetry-sdk + opentelemetry-exporter-otlp before enabling OTLP\")","typeGuard":"def tracing_ready() -> bool:\n    try:\n        from vllm.tracing import is_tracing_available\n        return is_tracing_available()\n    except Exception:\n        return False","tryCatchPattern":null,"preventionTips":["Bake OTel packages into serving images whenever the endpoint flag is templated in.","Smoke-test the import (python -c 'from vllm.tracing import is_tracing_available; assert is_tracing_available()') in CI."],"tags":["vllm","config","observability","opentelemetry","dependencies"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}