{"record":{"id":"7a0d8b075cf830ae","repo":"apache/pulsar","slug":"label-name-s-is-invalid-opentelemetry-reserves","errorCode":null,"errorMessage":"Label name '%s' is invalid: OpenTelemetry reserves all labels starting with 'otel_' or 'otel.' for internal use","messagePattern":"Label name '(.+?)' is invalid: OpenTelemetry reserves all labels starting with 'otel_' or 'otel\\.' for internal use","errorType":"http","errorClass":"org.apache.pulsar.broker.admin.RestException","httpStatus":400,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java","lineNumber":2571,"sourceCode":"        }\n\n        // Prometheus reserves all labels starting with \"__\" for internal use.\n        if (labelName.startsWith(\"__\")) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                    String.format(\"Label name '%s' is invalid: Prometheus reserves all labels starting with '__' \"\n                            + \"for internal use\", labelName));\n        }\n\n        // Pulsar reserves all labels starting with \"pulsar_\" or \"pulsar.\" for internal use.\n        if (labelName.endsWith(\"pulsar.\") || labelName.endsWith(\"pulsar_\")) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                    String.format(\"Label name '%s' is invalid: Pulsar reserves all labels starting with 'pulsar_' \"\n                            + \"or 'pulsar.' for internal use\", labelName));\n        }\n\n        // OpenTelemetry reserves all labels starting with \"otel_\" or \"otel.\" for internal use.\n        if (labelName.startsWith(\"otel.\") || labelName.startsWith(\"otel_\")) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                    String.format(\"Label name '%s' is invalid: OpenTelemetry reserves all labels starting with \"\n                            + \"'otel_' or 'otel.' for internal use\", labelName));\n        }\n\n        boolean matches = METRICS_LABEL_NAME_PATTERN.matcher(labelName).matches();\n        if (!matches) {\n            throw new RestException(Response.Status.BAD_REQUEST,\n                String.format(\"Label name '%s' is invalid: must match the regex [a-zA-Z_][a-zA-Z0-9_]*\", labelName));\n        }\n\n    }\n}\n","sourceCodeStart":2553,"sourceCodeEnd":2584,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java#L2553-L2584","documentation":"OpenTelemetry reserves label/attribute names starting with \"otel_\" or containing the \"otel.\" namespace for its internal use; Pulsar mirrors that reservation and rejects such metric label names with HTTP 400 via isValidMetricsName. This prevents collisions with OpenTelemetry SDK-generated labels.","triggerScenarios":"Registering a custom metrics label whose name starts with \"otel.\" or \"otel_\" (e.g. \"otel_custom\") through the broker metrics API.","commonSituations":"Mirroring OTel attribute naming in custom broker metrics; tooling that prefixes labels with otel_ to tag them for OpenTelemetry pipelines; reusing OTel semantic-convention names as Pulsar labels.","solutions":["Rename the label to avoid the \"otel_\" prefix and \"otel.\" namespace (e.g. \"telemetry_custom\").","Keep OTel-specific metadata in a separate attribute set rather than Pulsar metric labels.","Add pre-submission checks in tooling that generate label names to reject reserved OTel prefixes."],"exampleFix":"// before\nmetrics.registerLabel(\"otel_deployment\");\n\n// after\nmetrics.registerLabel(\"deployment_info\");","handlingStrategy":"validation","validationCode":"if (labelName.startsWith(\"otel_\") || labelName.startsWith(\"otel.\")) {\n    throw new IllegalArgumentException(\"label name uses reserved OpenTelemetry namespace: \" + labelName);\n}","typeGuard":"boolean isOtelSafe(String name) {\n    return name != null && !name.startsWith(\"otel_\") && !name.startsWith(\"otel.\");\n}","tryCatchPattern":"try {\n    metricsApi.registerLabel(labelName);\n} catch (RestException e) {\n    if (e.getResponse().getStatus() == 400 && (labelName.startsWith(\"otel_\") || labelName.startsWith(\"otel.\"))) {\n        log.error(\"Label '{}' collides with OpenTelemetry reserved namespace\", labelName);\n    }\n}","preventionTips":["Do not prefix custom labels with otel_ or otel.","Keep OTel-specific attributes in the OTel SDK, not Pulsar metric labels","Lint label generators for reserved OTel namespaces"],"tags":["metrics","opentelemetry","validation","reserved-prefix"],"backgroundTag":"metrics-label-name-invalid","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}