diff --git a/src/platform/packages/shared/kbn-otel-semantic-conventions/assets/resolved-semconv.yaml b/src/platform/packages/shared/kbn-otel-semantic-conventions/assets/resolved-semconv.yaml index 44faf8924c196..c8144c93f1536 100644 --- a/src/platform/packages/shared/kbn-otel-semantic-conventions/assets/resolved-semconv.yaml +++ b/src/platform/packages/shared/kbn-otel-semantic-conventions/assets/resolved-semconv.yaml @@ -2785,7 +2785,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -3070,7 +3070,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -3266,7 +3266,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -4047,7 +4047,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -4060,18 +4060,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -4084,11 +4084,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -4096,7 +4096,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -4106,7 +4108,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -4236,7 +4238,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -4249,18 +4251,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -4273,11 +4275,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -4787,7 +4789,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -4800,11 +4802,11 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -4812,7 +4814,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -4822,7 +4826,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -8840,6 +8844,234 @@ groups: - stability locally_overridden_fields: - role + - id: entity.k8s.service + type: entity + brief: | + A Kubernetes Service object. + stability: development + attributes: + - name: k8s.service.annotation + type: template[string] + brief: | + The annotation placed on the Service, the `` being the annotation name, the value being the annotation value, even if the value is empty. + examples: + - 'true' + - '' + requirement_level: opt_in + note: | + Examples: + + - An annotation `prometheus.io/scrape` with value `true` SHOULD be recorded as + the `k8s.service.annotation.prometheus.io/scrape` attribute with value `"true"`. + - An annotation `data` with empty string value SHOULD be recorded as + the `k8s.service.annotation.data` attribute with value `""`. + stability: development + role: descriptive + - name: k8s.service.label + type: template[string] + brief: | + The label placed on the Service, the `` being the label name, the value being the label value, even if the value is empty. + examples: + - my-service + - '' + requirement_level: opt_in + note: | + Examples: + + - A label `app` with value `my-service` SHOULD be recorded as + the `k8s.service.label.app` attribute with value `"my-service"`. + - A label `data` with empty string value SHOULD be recorded as + the `k8s.service.label.data` attribute with value `""`. + stability: development + role: descriptive + - name: k8s.service.name + type: string + brief: | + The name of the Service. + examples: + - my-service + requirement_level: recommended + stability: development + role: descriptive + - name: k8s.service.publish_not_ready_addresses + type: boolean + brief: | + Whether the Service publishes not-ready endpoints. + examples: + - true + - false + requirement_level: opt_in + note: | + Whether the Service is configured to publish endpoints before the pods are ready. + This attribute is typically used to indicate that a Service (such as a headless + Service for a StatefulSet) allows peer discovery before pods pass their readiness probes. + It aligns with the `publishNotReadyAddresses` field of the + [K8s ServiceSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec). + stability: development + role: descriptive + - name: k8s.service.selector + type: template[string] + brief: | + The selector key-value pair placed on the Service, the `` being the selector key, the value being the selector value. + examples: + - my-app + - v1 + requirement_level: opt_in + note: | + These selectors are used to correlate with pod labels. Each selector key-value pair becomes a separate attribute. + + Examples: + + - A selector `app=my-app` SHOULD be recorded as + the `k8s.service.selector.app` attribute with value `"my-app"`. + - A selector `version=v1` SHOULD be recorded as + the `k8s.service.selector.version` attribute with value `"v1"`. + stability: development + role: descriptive + - name: k8s.service.traffic_distribution + type: string + brief: | + The traffic distribution policy for the Service. + examples: + - PreferSameZone + - PreferSameNode + requirement_level: opt_in + note: | + Specifies how traffic is distributed to endpoints for this Service. + This attribute aligns with the `trafficDistribution` field of the + [K8s ServiceSpec](https://kubernetes.io/docs/reference/networking/virtual-ips/#traffic-distribution). + Known values include `PreferSameZone` (prefer endpoints in the same zone as the client) and + `PreferSameNode` (prefer endpoints on the same node, fallback to same zone, then cluster-wide). + If this field is not set on the Service, the attribute SHOULD NOT be emitted. + When not set, Kubernetes distributes traffic evenly across all endpoints cluster-wide. + stability: development + role: descriptive + - name: k8s.service.type + type: + members: + - id: cluster_ip + value: ClusterIP + brief: ClusterIP service type + stability: development + - id: node_port + value: NodePort + brief: NodePort service type + stability: development + - id: load_balancer + value: LoadBalancer + brief: LoadBalancer service type + stability: development + - id: external_name + value: ExternalName + brief: ExternalName service type + stability: development + brief: | + The type of the Kubernetes Service. + examples: + - ClusterIP + - NodePort + - LoadBalancer + requirement_level: recommended + note: | + This attribute aligns with the `type` field of the + [K8s ServiceSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec). + stability: development + role: descriptive + - name: k8s.service.uid + type: string + brief: | + The UID of the Service. + examples: + - 275ecb36-5aa8-4c2a-9c47-d8bb681b9aff + requirement_level: recommended + stability: development + role: identifying + name: k8s.service + lineage: + provenance: + registry_id: main + path: /home/weaver/source/k8s/entities.yaml + attributes: + k8s.service.annotation: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - role + k8s.service.label: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - role + k8s.service.name: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + locally_overridden_fields: + - role + k8s.service.publish_not_ready_addresses: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - role + k8s.service.selector: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - role + k8s.service.traffic_distribution: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - role + k8s.service.type: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + locally_overridden_fields: + - role + k8s.service.uid: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + locally_overridden_fields: + - role - id: entity.k8s.statefulset type: entity brief: | @@ -10735,6 +10967,79 @@ groups: examples: - v3-1677874579383-6381583661209 requirement_level: required + - id: event.db.client.operation.exception + type: event + brief: | + This event represents an exception that occurred during a database client operation, such as connection failures, query errors, timeouts, or other errors that prevent the operation from completing successfully. + note: | + This event SHOULD be recorded when an exception occurs during database client operations. + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding database client span. + stability: development + attributes: + - name: exception.message + type: string + brief: The exception message. + examples: + - Division by zero + - Can't convert 'int' object to str implicitly + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + note: | + > [!WARNING] + > + > This attribute may contain sensitive information. + stability: stable + - name: exception.stacktrace + type: string + brief: | + A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. + examples: | + Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) + requirement_level: recommended + stability: stable + - name: exception.type + type: string + brief: | + The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. + examples: + - java.net.ConnectException + - OSError + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + stability: stable + name: db.client.operation.exception + lineage: + provenance: + registry_id: main + path: /home/weaver/source/db/events.yaml + attributes: + exception.message: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + exception.stacktrace: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + exception.type: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level - id: event.device.app.lifecycle type: event brief: | @@ -10925,17 +11230,6 @@ groups: A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. stability: release_candidate attributes: - - name: error.message - type: string - brief: A message providing more detail about an error in human-readable form. - examples: - - 'Unexpected input type: string' - - The user has exceeded their storage quota - requirement_level: - recommended: If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error. - note: | - Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid. - stability: development - name: error.type type: members: @@ -10975,6 +11269,18 @@ groups: - 5157782b-2203-4c80-a857-dbbd5e7761db requirement_level: recommended stability: release_candidate + - name: feature_flag.error.message + type: string + brief: | + A message providing more detail about an error that occurred during feature flag evaluation in human-readable form. + examples: + - 'Unexpected input type: string' + - The user has exceeded their storage quota + requirement_level: + recommended: If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error. + note: | + Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `feature_flag.error.message` may enumerate which context keys are missing or invalid. + stability: release_candidate - name: feature_flag.key type: string brief: The lookup key of the feature flag. @@ -11095,32 +11401,32 @@ groups: registry_id: main path: /home/weaver/source/feature-flags/events.yaml attributes: - error.message: + error.type: source_group: registry.error inherited_fields: - brief - - examples - stability locally_overridden_fields: + - examples - note - requirement_level - error.type: - source_group: registry.error + feature_flag.context.id: + source_group: registry.feature_flag inherited_fields: - brief - - stability - locally_overridden_fields: - examples - note + - stability + locally_overridden_fields: - requirement_level - feature_flag.context.id: + feature_flag.error.message: source_group: registry.feature_flag inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level feature_flag.key: source_group: registry.feature_flag @@ -12958,6 +13264,226 @@ groups: - customer requirement_level: conditionally_required: if available and not equal to `user`. + - id: event.http.client.request.exception + type: event + brief: | + This event represents an exception that occurred during an HTTP client request, such as network failures, timeouts, or other errors that prevent the request from completing successfully. + note: | + This event SHOULD be recorded when an exception occurs during HTTP client operations. + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + Some HTTP client frameworks generate artificial exceptions for non-successful HTTP status codes (e.g., 404 Not Found). When possible, instrumentations SHOULD NOT record these artificial exceptions, or SHOULD set the severity to DEBUG (severity number 5). + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP client span. + stability: development + attributes: + - name: exception.message + type: string + brief: The exception message. + examples: + - Division by zero + - Can't convert 'int' object to str implicitly + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + note: | + > [!WARNING] + > + > This attribute may contain sensitive information. + stability: stable + - name: exception.stacktrace + type: string + brief: | + A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. + examples: | + Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) + requirement_level: recommended + stability: stable + - name: exception.type + type: string + brief: | + The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. + examples: + - java.net.ConnectException + - OSError + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + stability: stable + name: http.client.request.exception + lineage: + provenance: + registry_id: main + path: /home/weaver/source/http/events.yaml + attributes: + exception.message: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + exception.stacktrace: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + exception.type: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - id: event.http.server.request.exception + type: event + brief: | + This event represents an exception that occurred during HTTP server request processing, such as application errors, internal failures, or other exceptions that prevent the server from successfully handling the request. + note: | + This event SHOULD be recorded when an exception occurs during HTTP server request processing. + Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP server span. + stability: development + attributes: + - name: exception.message + type: string + brief: The exception message. + examples: + - Division by zero + - Can't convert 'int' object to str implicitly + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + note: | + > [!WARNING] + > + > This attribute may contain sensitive information. + stability: stable + - name: exception.stacktrace + type: string + brief: | + A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. + examples: | + Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) + requirement_level: recommended + stability: stable + - name: exception.type + type: string + brief: | + The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. + examples: + - java.net.ConnectException + - OSError + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + stability: stable + name: http.server.request.exception + lineage: + provenance: + registry_id: main + path: /home/weaver/source/http/events.yaml + attributes: + exception.message: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + exception.stacktrace: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + exception.type: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - id: event.rpc.client.call.exception + type: event + brief: | + This event represents an exception that occurred during an outgoing RPC call, such as network failures, timeouts, serialization errors, or other errors that prevent the call from completing successfully. + note: | + This event SHOULD be recorded when an exception occurs during RPC client call operations. + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding RPC client span. + stability: development + attributes: + - name: exception.message + type: string + brief: The exception message. + examples: + - Division by zero + - Can't convert 'int' object to str implicitly + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + note: | + > [!WARNING] + > + > This attribute may contain sensitive information. + stability: stable + - name: exception.stacktrace + type: string + brief: | + A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. + examples: | + Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) + requirement_level: recommended + stability: stable + - name: exception.type + type: string + brief: | + The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. + examples: + - java.net.ConnectException + - OSError + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + stability: stable + name: rpc.client.call.exception + lineage: + provenance: + registry_id: main + path: /home/weaver/source/rpc/events.yaml + attributes: + exception.message: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + exception.stacktrace: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + exception.type: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level - id: event.rpc.message type: event brief: Describes a message sent or received within the context of an RPC call. @@ -13050,6 +13576,79 @@ groups: - stability locally_overridden_fields: - requirement_level + - id: event.rpc.server.call.exception + type: event + brief: | + This event represents an exception that occurred during incoming RPC call processing, such as application errors, internal failures, or other exceptions that prevent the server from successfully handling the call. + note: | + This event SHOULD be recorded when an exception occurs during RPC server call processing. + Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding RPC server span. + stability: development + attributes: + - name: exception.message + type: string + brief: The exception message. + examples: + - Division by zero + - Can't convert 'int' object to str implicitly + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + note: | + > [!WARNING] + > + > This attribute may contain sensitive information. + stability: stable + - name: exception.stacktrace + type: string + brief: | + A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. + examples: | + Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) + requirement_level: recommended + stability: stable + - name: exception.type + type: string + brief: | + The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. + examples: + - java.net.ConnectException + - OSError + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + stability: stable + name: rpc.server.call.exception + lineage: + provenance: + registry_id: main + path: /home/weaver/source/rpc/events.yaml + attributes: + exception.message: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + exception.stacktrace: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - requirement_level + - stability + exception.type: + source_group: registry.exception + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level - id: event.session.end type: event brief: | @@ -14101,7 +14700,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate lineage: provenance: registry_id: main @@ -14519,7 +15118,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate lineage: provenance: registry_id: main @@ -18835,7 +19434,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -19120,7 +19719,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -19406,7 +20005,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -28746,9 +29345,12 @@ groups: annotations: code_generation: metric_value_type: double - - id: metric.gen_ai.client.token.usage + - id: metric.gen_ai.client.operation.time_per_output_chunk type: metric - brief: Number of input and output tokens used. + brief: | + Time per output chunk, recorded for each chunk received after the first one, measured as the time elapsed from the end of the previous chunk to the end of the current chunk. + note: | + This metrics SHOULD be reported for streaming calls and SHOULD NOT be reported otherwise. stability: development attributes: - name: gen_ai.operation.name @@ -28896,31 +29498,6 @@ groups: - gpt-4-0613 requirement_level: recommended stability: development - - name: gen_ai.token.type - type: - members: - - id: input - value: input - brief: Input tokens (prompt, input, etc.) - stability: development - - id: completion - value: output - brief: Output tokens (completion, response, etc.) - stability: development - deprecated: - reason: renamed - renamed_to: output - note: Replaced by `output`. - - id: output - value: output - brief: Output tokens (completion, response, etc.) - stability: development - brief: The type of token being counted. - examples: - - input - - output - requirement_level: required - stability: development - name: server.address type: string brief: GenAI server address. @@ -28944,9 +29521,9 @@ groups: note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable - metric_name: gen_ai.client.token.usage + metric_name: gen_ai.client.operation.time_per_output_chunk instrument: histogram - unit: '{token}' + unit: s lineage: provenance: registry_id: main @@ -28986,7 +29563,236 @@ groups: - stability locally_overridden_fields: - requirement_level - gen_ai.token.type: + server.address: + source_group: registry.server + inherited_fields: + - examples + - note + - stability + locally_overridden_fields: + - brief + - requirement_level + server.port: + source_group: registry.server + inherited_fields: + - examples + - note + - stability + locally_overridden_fields: + - brief + - requirement_level + annotations: + code_generation: + metric_value_type: double + - id: metric.gen_ai.client.operation.time_to_first_chunk + type: metric + brief: Time to receive the first chunk, measured from when the client issues the generation request to when the first chunk is received in the response stream. + note: | + This metrics SHOULD be reported for streaming calls and SHOULD NOT be reported otherwise. + stability: development + attributes: + - name: gen_ai.operation.name + type: + members: + - id: chat + value: chat + brief: Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) + stability: development + - id: generate_content + value: generate_content + brief: Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) + stability: development + - id: text_completion + value: text_completion + brief: Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) + stability: development + - id: embeddings + value: embeddings + brief: Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) + stability: development + - id: retrieval + value: retrieval + brief: Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) + stability: development + - id: create_agent + value: create_agent + brief: Create GenAI agent + stability: development + - id: invoke_agent + value: invoke_agent + brief: Invoke GenAI agent + stability: development + - id: execute_tool + value: execute_tool + brief: Execute a tool + stability: development + brief: The name of the operation being performed. + requirement_level: required + note: | + If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + stability: development + - name: gen_ai.provider.name + type: + members: + - id: openai + value: openai + brief: '[OpenAI](https://openai.com/)' + stability: development + - id: gcp.gen_ai + value: gcp.gen_ai + brief: Any Google generative AI endpoint + note: | + May be used when specific backend is unknown. + stability: development + - id: gcp.vertex_ai + value: gcp.vertex_ai + brief: '[Vertex AI](https://cloud.google.com/vertex-ai)' + note: | + Used when accessing the 'aiplatform.googleapis.com' endpoint. + stability: development + - id: gcp.gemini + value: gcp.gemini + brief: '[Gemini](https://cloud.google.com/products/gemini)' + note: | + Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + stability: development + - id: anthropic + value: anthropic + brief: '[Anthropic](https://www.anthropic.com/)' + stability: development + - id: cohere + value: cohere + brief: '[Cohere](https://cohere.com/)' + stability: development + - id: azure.ai.inference + value: azure.ai.inference + brief: Azure AI Inference + stability: development + - id: azure.ai.openai + value: azure.ai.openai + brief: '[Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/)' + stability: development + - id: ibm.watsonx.ai + value: ibm.watsonx.ai + brief: '[IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai)' + stability: development + - id: aws.bedrock + value: aws.bedrock + brief: '[AWS Bedrock](https://aws.amazon.com/bedrock)' + stability: development + - id: perplexity + value: perplexity + brief: '[Perplexity](https://www.perplexity.ai/)' + stability: development + - id: x_ai + value: x_ai + brief: '[xAI](https://x.ai/)' + stability: development + - id: deepseek + value: deepseek + brief: '[DeepSeek](https://www.deepseek.com/)' + stability: development + - id: groq + value: groq + brief: '[Groq](https://groq.com/)' + stability: development + - id: mistral_ai + value: mistral_ai + brief: '[Mistral AI](https://mistral.ai/)' + stability: development + brief: The Generative AI provider as identified by the client or server instrumentation. + requirement_level: required + note: | + The attribute SHOULD be set based on the instrumentation's best + knowledge and may differ from the actual model provider. + + Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms + are accessible using the OpenAI REST API and corresponding client libraries, + but may proxy or host models from different providers. + + The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` + attributes may help identify the actual system in use. + + The `gen_ai.provider.name` attribute acts as a discriminator that + identifies the GenAI telemetry format flavor specific to that provider + within GenAI semantic conventions. + It SHOULD be set consistently with provider-specific attributes and signals. + For example, GenAI spans, metrics, and events related to AWS Bedrock + should have the `gen_ai.provider.name` set to `aws.bedrock` and include + applicable `aws.bedrock.*` attributes and are not expected to include + `openai.*` attributes. + stability: development + - name: gen_ai.request.model + type: string + brief: The name of the GenAI model a request is being made to. + examples: gpt-4 + requirement_level: + conditionally_required: If available. + stability: development + - name: gen_ai.response.model + type: string + brief: The name of the model that generated the response. + examples: + - gpt-4-0613 + requirement_level: recommended + stability: development + - name: server.address + type: string + brief: GenAI server address. + examples: + - example.com + - 10.1.2.80 + - /tmp/my.sock + requirement_level: recommended + note: | + When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + stability: stable + - name: server.port + type: int + brief: GenAI server port. + examples: + - 80 + - 8080 + - 443 + requirement_level: + conditionally_required: If `server.address` is set. + note: | + When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + stability: stable + metric_name: gen_ai.client.operation.time_to_first_chunk + instrument: histogram + unit: s + lineage: + provenance: + registry_id: main + path: /home/weaver/source/gen-ai/metrics.yaml + attributes: + gen_ai.operation.name: + source_group: registry.gen_ai + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.provider.name: + source_group: registry.gen_ai + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.request.model: + source_group: registry.gen_ai + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.response.model: source_group: registry.gen_ai inherited_fields: - brief @@ -29015,34 +29821,304 @@ groups: - requirement_level annotations: code_generation: - metric_value_type: int - - id: metric.gen_ai.server.request.duration + metric_value_type: double + - id: metric.gen_ai.client.token.usage type: metric - brief: Generative AI server request duration such as time-to-last byte or last output token. + brief: Number of input and output tokens used. stability: development attributes: - - name: error.type - type: - members: - - id: other - value: _OTHER - brief: | - A fallback error value to be used when the instrumentation doesn't define a custom value. - stability: stable - brief: | - Describes a class of error the operation ended with. - examples: - - timeout - - java.net.UnknownHostException - - server_certificate_invalid - - '500' - requirement_level: - conditionally_required: if the operation ended in an error - note: | - The `error.type` SHOULD match the error code returned by the Generative AI service, - the canonical name of exception that occurred, or another low-cardinality error identifier. - Instrumentations SHOULD document the list of errors they report. - stability: stable + - name: gen_ai.operation.name + type: + members: + - id: chat + value: chat + brief: Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) + stability: development + - id: generate_content + value: generate_content + brief: Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) + stability: development + - id: text_completion + value: text_completion + brief: Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) + stability: development + - id: embeddings + value: embeddings + brief: Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) + stability: development + - id: retrieval + value: retrieval + brief: Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) + stability: development + - id: create_agent + value: create_agent + brief: Create GenAI agent + stability: development + - id: invoke_agent + value: invoke_agent + brief: Invoke GenAI agent + stability: development + - id: execute_tool + value: execute_tool + brief: Execute a tool + stability: development + brief: The name of the operation being performed. + requirement_level: required + note: | + If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + stability: development + - name: gen_ai.provider.name + type: + members: + - id: openai + value: openai + brief: '[OpenAI](https://openai.com/)' + stability: development + - id: gcp.gen_ai + value: gcp.gen_ai + brief: Any Google generative AI endpoint + note: | + May be used when specific backend is unknown. + stability: development + - id: gcp.vertex_ai + value: gcp.vertex_ai + brief: '[Vertex AI](https://cloud.google.com/vertex-ai)' + note: | + Used when accessing the 'aiplatform.googleapis.com' endpoint. + stability: development + - id: gcp.gemini + value: gcp.gemini + brief: '[Gemini](https://cloud.google.com/products/gemini)' + note: | + Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. + stability: development + - id: anthropic + value: anthropic + brief: '[Anthropic](https://www.anthropic.com/)' + stability: development + - id: cohere + value: cohere + brief: '[Cohere](https://cohere.com/)' + stability: development + - id: azure.ai.inference + value: azure.ai.inference + brief: Azure AI Inference + stability: development + - id: azure.ai.openai + value: azure.ai.openai + brief: '[Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/)' + stability: development + - id: ibm.watsonx.ai + value: ibm.watsonx.ai + brief: '[IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai)' + stability: development + - id: aws.bedrock + value: aws.bedrock + brief: '[AWS Bedrock](https://aws.amazon.com/bedrock)' + stability: development + - id: perplexity + value: perplexity + brief: '[Perplexity](https://www.perplexity.ai/)' + stability: development + - id: x_ai + value: x_ai + brief: '[xAI](https://x.ai/)' + stability: development + - id: deepseek + value: deepseek + brief: '[DeepSeek](https://www.deepseek.com/)' + stability: development + - id: groq + value: groq + brief: '[Groq](https://groq.com/)' + stability: development + - id: mistral_ai + value: mistral_ai + brief: '[Mistral AI](https://mistral.ai/)' + stability: development + brief: The Generative AI provider as identified by the client or server instrumentation. + requirement_level: required + note: | + The attribute SHOULD be set based on the instrumentation's best + knowledge and may differ from the actual model provider. + + Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms + are accessible using the OpenAI REST API and corresponding client libraries, + but may proxy or host models from different providers. + + The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address` + attributes may help identify the actual system in use. + + The `gen_ai.provider.name` attribute acts as a discriminator that + identifies the GenAI telemetry format flavor specific to that provider + within GenAI semantic conventions. + It SHOULD be set consistently with provider-specific attributes and signals. + For example, GenAI spans, metrics, and events related to AWS Bedrock + should have the `gen_ai.provider.name` set to `aws.bedrock` and include + applicable `aws.bedrock.*` attributes and are not expected to include + `openai.*` attributes. + stability: development + - name: gen_ai.request.model + type: string + brief: The name of the GenAI model a request is being made to. + examples: gpt-4 + requirement_level: + conditionally_required: If available. + stability: development + - name: gen_ai.response.model + type: string + brief: The name of the model that generated the response. + examples: + - gpt-4-0613 + requirement_level: recommended + stability: development + - name: gen_ai.token.type + type: + members: + - id: input + value: input + brief: Input tokens (prompt, input, etc.) + stability: development + - id: completion + value: output + brief: Output tokens (completion, response, etc.) + stability: development + deprecated: + reason: renamed + renamed_to: output + note: Replaced by `output`. + - id: output + value: output + brief: Output tokens (completion, response, etc.) + stability: development + brief: The type of token being counted. + examples: + - input + - output + requirement_level: required + stability: development + - name: server.address + type: string + brief: GenAI server address. + examples: + - example.com + - 10.1.2.80 + - /tmp/my.sock + requirement_level: recommended + note: | + When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + stability: stable + - name: server.port + type: int + brief: GenAI server port. + examples: + - 80 + - 8080 + - 443 + requirement_level: + conditionally_required: If `server.address` is set. + note: | + When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + stability: stable + metric_name: gen_ai.client.token.usage + instrument: histogram + unit: '{token}' + lineage: + provenance: + registry_id: main + path: /home/weaver/source/gen-ai/metrics.yaml + attributes: + gen_ai.operation.name: + source_group: registry.gen_ai + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.provider.name: + source_group: registry.gen_ai + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.request.model: + source_group: registry.gen_ai + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.response.model: + source_group: registry.gen_ai + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + gen_ai.token.type: + source_group: registry.gen_ai + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + server.address: + source_group: registry.server + inherited_fields: + - examples + - note + - stability + locally_overridden_fields: + - brief + - requirement_level + server.port: + source_group: registry.server + inherited_fields: + - examples + - note + - stability + locally_overridden_fields: + - brief + - requirement_level + annotations: + code_generation: + metric_value_type: int + - id: metric.gen_ai.server.request.duration + type: metric + brief: Generative AI server request duration such as time-to-last byte or last output token. + stability: development + attributes: + - name: error.type + type: + members: + - id: other + value: _OTHER + brief: | + A fallback error value to be used when the instrumentation doesn't define a custom value. + stability: stable + brief: | + Describes a class of error the operation ended with. + examples: + - timeout + - java.net.UnknownHostException + - server_certificate_invalid + - '500' + requirement_level: + conditionally_required: if the operation ended in an error + note: | + The `error.type` SHOULD match the error code returned by the Generative AI service, + the canonical name of exception that occurred, or another low-cardinality error identifier. + Instrumentations SHOULD document the list of errors they report. + stability: stable - name: gen_ai.operation.name type: members: @@ -30001,7 +31077,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -30476,7 +31552,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -30769,7 +31845,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -31063,7 +32139,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -31321,7 +32397,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -31528,7 +32604,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -31856,7 +32932,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -32186,7 +33262,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -38571,6 +39647,20 @@ groups: annotations: code_generation: metric_value_type: int + - id: metric.jvm.file_descriptor.limit + type: metric + brief: Measure of max open file descriptors as reported by the JVM. + stability: development + metric_name: jvm.file_descriptor.limit + instrument: updowncounter + unit: '{file_descriptor}' + lineage: + provenance: + registry_id: main + path: /home/weaver/source/jvm/metrics-experimental.yaml + annotations: + code_generation: + metric_value_type: int - id: metric.jvm.gc.duration type: metric brief: Duration of JVM garbage collection actions. @@ -42675,6 +43765,174 @@ groups: annotations: code_generation: metric_value_type: int + - id: metric.k8s.service.endpoint.count + type: metric + brief: Number of endpoints for a service by condition and address type. + note: | + This metric is derived from the Kubernetes [EndpointSlice API](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + It reports the number of network endpoints backing a Service, broken down by their condition and address type. + + In dual-stack or multi-protocol clusters, separate counts are reported for each address family (`IPv4`, `IPv6`, `FQDN`). + + When the optional `zone` attribute is enabled, counts are further broken down by availability zone for zone-aware monitoring. + + An endpoint may be reported under multiple conditions simultaneously (e.g., both `serving` and `terminating` during a graceful shutdown). + See [K8s EndpointConditions](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/) for more details. + + The conditions represent: + - `ready`: Endpoints capable of receiving new connections. + - `serving`: Endpoints currently handling traffic. + - `terminating`: Endpoints that are being phased out but may still be handling existing connections. + + For Services with `publishNotReadyAddresses` enabled (common for headless StatefulSets), + this metric will include endpoints that are published despite not being ready. + The `k8s.service.publish_not_ready_addresses` resource attribute indicates this setting. + stability: development + attributes: + - name: k8s.service.endpoint.address_type + type: + members: + - id: ipv4 + value: IPv4 + brief: IPv4 address type + stability: development + - id: ipv6 + value: IPv6 + brief: IPv6 address type + stability: development + - id: fqdn + value: FQDN + brief: FQDN address type + stability: development + brief: | + The address type of the service endpoint. + examples: + - IPv4 + - IPv6 + requirement_level: required + note: | + The network address family or type of the endpoint. + This attribute aligns with the `addressType` field of the + [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + It is used to differentiate metrics when a Service is backed by multiple address types + (e.g., in dual-stack clusters). + stability: development + - name: k8s.service.endpoint.condition + type: + members: + - id: ready + value: ready + brief: The endpoint is ready to receive new connections. + stability: development + - id: serving + value: serving + brief: The endpoint is currently handling traffic. + stability: development + - id: terminating + value: terminating + brief: The endpoint is in the process of shutting down. + stability: development + brief: | + The condition of the service endpoint. + examples: + - ready + - serving + - terminating + requirement_level: required + note: | + The current operational condition of the service endpoint. + An endpoint can have multiple conditions set at once (e.g., both `serving` and `terminating` during rollout). + This attribute aligns with the condition fields in the [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + stability: development + - name: k8s.service.endpoint.zone + type: string + brief: | + The zone of the service endpoint. + examples: + - us-east-1a + - us-west-2b + - zone-a + - '' + requirement_level: recommended + note: | + The zone where the endpoint is located, typically corresponding to a failure domain. + This attribute aligns with the `zone` field of endpoints in the + [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + It enables zone-aware monitoring of service endpoint distribution and supports + features like [Topology Aware Routing](https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/). + + If the zone is not populated (e.g., nodes without the `topology.kubernetes.io/zone` label), + the attribute value will be an empty string. + stability: development + metric_name: k8s.service.endpoint.count + instrument: gauge + unit: '{endpoint}' + lineage: + provenance: + registry_id: main + path: /home/weaver/source/k8s/metrics.yaml + attributes: + k8s.service.endpoint.address_type: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + k8s.service.endpoint.condition: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + k8s.service.endpoint.zone: + source_group: registry.k8s + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + entity_associations: + - k8s.service + annotations: + code_generation: + metric_value_type: int + - id: metric.k8s.service.load_balancer.ingress.count + type: metric + brief: Number of load balancer ingress points (external IPs/hostnames) assigned to the service. + note: | + This metric reports the number of external ingress points (IP addresses or hostnames) + assigned to a LoadBalancer Service. + + It is only emitted for Services of type `LoadBalancer` and reflects the assignments + made by the underlying infrastructure's load balancer controller in the + [.status.loadBalancer.ingress](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceStatus) field. + + A value of `0` indicates that no ingress points have been assigned yet (e.g., during provisioning). + A value greater than `1` may occur when multiple IPs or hostnames are assigned (e.g., dual-stack configurations). + + This metric signals that external endpoints have been assigned by the load balancer controller, but it does not + guarantee that the load balancer is healthy. + stability: development + metric_name: k8s.service.load_balancer.ingress.count + instrument: gauge + unit: '{ingress}' + lineage: + provenance: + registry_id: main + path: /home/weaver/source/k8s/metrics.yaml + entity_associations: + - k8s.service + annotations: + code_generation: + metric_value_type: int - id: metric.k8s.statefulset.current_pods type: metric brief: Deprecated, use `k8s.statefulset.pod.current` instead. @@ -44404,7 +45662,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: server.address type: string brief: Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. @@ -45093,7 +46351,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate metric_name: mcp.server.operation.duration instrument: histogram unit: s @@ -50272,7 +51530,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: server.address type: string brief: Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. @@ -52632,7 +53890,7 @@ groups: note: | When this metric is reported alongside an RPC client span, the metric value SHOULD be the same as the RPC client span duration. - stability: development + stability: release_candidate attributes: - name: error.type type: @@ -52698,7 +53956,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -52711,18 +53969,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -52735,11 +53993,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -52747,7 +54005,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -52757,7 +54017,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -52902,7 +54162,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -52915,18 +54175,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -52939,11 +54199,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -52951,7 +54211,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -52961,7 +54223,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -53103,7 +54365,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -53116,18 +54378,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -53140,11 +54402,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -53152,7 +54414,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -53162,7 +54426,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -53306,7 +54570,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -53319,18 +54583,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -53343,11 +54607,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -53355,7 +54619,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -53365,7 +54631,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -53507,7 +54773,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -53520,18 +54786,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -53544,11 +54810,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -53556,7 +54822,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -53566,7 +54834,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -53710,7 +54978,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -53723,18 +54991,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -53747,11 +55015,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -53759,7 +55027,9 @@ groups: requirement_level: conditionally_required: If available. note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -53769,7 +55039,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. stability: stable @@ -53843,7 +55113,7 @@ groups: note: | When this metric is reported alongside an RPC server span, the metric value SHOULD be the same as the RPC server span duration. - stability: development + stability: release_candidate attributes: - name: error.type type: @@ -53909,7 +55179,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -53922,18 +55192,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -53946,11 +55216,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -54107,7 +55377,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -54120,18 +55390,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -54144,11 +55414,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -54302,7 +55572,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -54315,18 +55585,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -54339,11 +55609,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -54499,7 +55769,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -54512,18 +55782,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -54536,11 +55806,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -54694,7 +55964,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -54707,18 +55977,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -54731,11 +56001,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -54891,7 +56161,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -54904,18 +56174,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -54928,11 +56198,11 @@ groups: requirement_level: required note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -60193,6 +61463,29 @@ groups: - /bazinga/ requirement_level: recommended stability: development + - name: pprof.scope.default_sample_type + type: string + brief: | + Records the pprof's default_sample_type in the original profile. Not set if the default sample type was missing. + examples: + - cpu + requirement_level: recommended + note: | + This attribute, if present, MUST be set at the scope level (resource_profiles[].scope_profiles[].scope.attributes[]). + stability: development + - name: pprof.scope.sample_type_order + type: int[] + brief: | + Records the indexes of the sample types in the original profile. + examples: + - - 3 + - 0 + - 1 + - 2 + requirement_level: recommended + note: | + This attribute, if present, MUST be set at the scope level (resource_profiles[].scope_profiles[].scope.attributes[]). + stability: development lineage: provenance: registry_id: main @@ -60274,6 +61567,24 @@ groups: - stability locally_overridden_fields: - requirement_level + pprof.scope.default_sample_type: + source_group: registry.pprof + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + pprof.scope.sample_type_order: + source_group: registry.pprof + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level - id: process.zos type: attribute_group brief: A process running on a z/OS system. @@ -64952,20 +66263,6 @@ groups: brief: | This document defines the shared attributes used to report an error. attributes: - - name: error.message - type: string - brief: A message providing more detail about an error in human-readable form. - examples: - - 'Unexpected input type: string' - - The user has exceeded their storage quota - requirement_level: recommended - note: | - `error.message` should provide additional context and detail about an error. - It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`. - It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`. - - `error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status. - stability: development - name: error.type type: members: @@ -65008,6 +66305,33 @@ groups: registry_id: main path: /home/weaver/source/error/registry.yaml display_name: Error Attributes + - id: registry.error.deprecated + type: attribute_group + brief: | + This document defines deprecated attributes used to report an error. + attributes: + - name: error.message + type: string + brief: A message providing more detail about an error in human-readable form. + examples: + - 'Unexpected input type: string' + - The user has exceeded their storage quota + requirement_level: recommended + note: | + `error.message` should provide additional context and detail about an error. + It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`. + It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`. + + `error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status. + stability: development + deprecated: + reason: obsoleted + note: Use domain-specific error message attribute. For example, use `feature_flag.error.message` for feature flag errors. + lineage: + provenance: + registry_id: main + path: /home/weaver/source/error/deprecated/registry-deprecated.yaml + display_name: Deprecated Error Attributes - id: registry.event.deprecated type: attribute_group brief: | @@ -65320,6 +66644,15 @@ groups: - 5157782b-2203-4c80-a857-dbbd5e7761db requirement_level: recommended stability: release_candidate + - name: feature_flag.error.message + type: string + brief: | + A message providing more detail about an error that occurred during feature flag evaluation in human-readable form. + examples: + - 'Unexpected input type: string' + - The user has exceeded their storage quota + requirement_level: recommended + stability: release_candidate - name: feature_flag.key type: string brief: The lookup key of the feature flag. @@ -65442,15 +66775,15 @@ groups: attributes: - name: feature_flag.evaluation.error.message type: string - brief: Deprecated, use `error.message` instead. + brief: Deprecated, use `feature_flag.error.message` instead. examples: - Flag `header-color` expected type `string` but found type `number` requirement_level: recommended stability: development deprecated: reason: renamed - renamed_to: error.message - note: Replaced by `error.message`. + renamed_to: feature_flag.error.message + note: Replaced by `feature_flag.error.message`. - name: feature_flag.evaluation.reason type: members: @@ -66130,6 +67463,14 @@ groups: - Fiction Writer requirement_level: recommended stability: development + - name: gen_ai.agent.version + type: string + brief: The version of the GenAI agent. + examples: + - 1.0.0 + - 2025-05-01T00:00:00.000Z + requirement_level: recommended + stability: development - name: gen_ai.conversation.id type: string brief: The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. @@ -67968,7 +69309,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -69331,6 +70672,209 @@ groups: - 275ecb36-5aa8-4c2a-9c47-d8bb681b9aff requirement_level: recommended stability: development + - name: k8s.service.annotation + type: template[string] + brief: | + The annotation placed on the Service, the `` being the annotation name, the value being the annotation value, even if the value is empty. + examples: + - 'true' + - '' + requirement_level: recommended + note: | + Examples: + + - An annotation `prometheus.io/scrape` with value `true` SHOULD be recorded as + the `k8s.service.annotation.prometheus.io/scrape` attribute with value `"true"`. + - An annotation `data` with empty string value SHOULD be recorded as + the `k8s.service.annotation.data` attribute with value `""`. + stability: development + - name: k8s.service.endpoint.address_type + type: + members: + - id: ipv4 + value: IPv4 + brief: IPv4 address type + stability: development + - id: ipv6 + value: IPv6 + brief: IPv6 address type + stability: development + - id: fqdn + value: FQDN + brief: FQDN address type + stability: development + brief: | + The address type of the service endpoint. + examples: + - IPv4 + - IPv6 + requirement_level: recommended + note: | + The network address family or type of the endpoint. + This attribute aligns with the `addressType` field of the + [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + It is used to differentiate metrics when a Service is backed by multiple address types + (e.g., in dual-stack clusters). + stability: development + - name: k8s.service.endpoint.condition + type: + members: + - id: ready + value: ready + brief: The endpoint is ready to receive new connections. + stability: development + - id: serving + value: serving + brief: The endpoint is currently handling traffic. + stability: development + - id: terminating + value: terminating + brief: The endpoint is in the process of shutting down. + stability: development + brief: | + The condition of the service endpoint. + examples: + - ready + - serving + - terminating + requirement_level: recommended + note: | + The current operational condition of the service endpoint. + An endpoint can have multiple conditions set at once (e.g., both `serving` and `terminating` during rollout). + This attribute aligns with the condition fields in the [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + stability: development + - name: k8s.service.endpoint.zone + type: string + brief: | + The zone of the service endpoint. + examples: + - us-east-1a + - us-west-2b + - zone-a + - '' + requirement_level: recommended + note: | + The zone where the endpoint is located, typically corresponding to a failure domain. + This attribute aligns with the `zone` field of endpoints in the + [K8s EndpointSlice](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1/). + It enables zone-aware monitoring of service endpoint distribution and supports + features like [Topology Aware Routing](https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/). + + If the zone is not populated (e.g., nodes without the `topology.kubernetes.io/zone` label), + the attribute value will be an empty string. + stability: development + - name: k8s.service.label + type: template[string] + brief: | + The label placed on the Service, the `` being the label name, the value being the label value, even if the value is empty. + examples: + - my-service + - '' + requirement_level: recommended + note: | + Examples: + + - A label `app` with value `my-service` SHOULD be recorded as + the `k8s.service.label.app` attribute with value `"my-service"`. + - A label `data` with empty string value SHOULD be recorded as + the `k8s.service.label.data` attribute with value `""`. + stability: development + - name: k8s.service.name + type: string + brief: | + The name of the Service. + examples: + - my-service + requirement_level: recommended + stability: development + - name: k8s.service.publish_not_ready_addresses + type: boolean + brief: | + Whether the Service publishes not-ready endpoints. + examples: + - true + - false + requirement_level: recommended + note: | + Whether the Service is configured to publish endpoints before the pods are ready. + This attribute is typically used to indicate that a Service (such as a headless + Service for a StatefulSet) allows peer discovery before pods pass their readiness probes. + It aligns with the `publishNotReadyAddresses` field of the + [K8s ServiceSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec). + stability: development + - name: k8s.service.selector + type: template[string] + brief: | + The selector key-value pair placed on the Service, the `` being the selector key, the value being the selector value. + examples: + - my-app + - v1 + requirement_level: recommended + note: | + These selectors are used to correlate with pod labels. Each selector key-value pair becomes a separate attribute. + + Examples: + + - A selector `app=my-app` SHOULD be recorded as + the `k8s.service.selector.app` attribute with value `"my-app"`. + - A selector `version=v1` SHOULD be recorded as + the `k8s.service.selector.version` attribute with value `"v1"`. + stability: development + - name: k8s.service.traffic_distribution + type: string + brief: | + The traffic distribution policy for the Service. + examples: + - PreferSameZone + - PreferSameNode + requirement_level: recommended + note: | + Specifies how traffic is distributed to endpoints for this Service. + This attribute aligns with the `trafficDistribution` field of the + [K8s ServiceSpec](https://kubernetes.io/docs/reference/networking/virtual-ips/#traffic-distribution). + Known values include `PreferSameZone` (prefer endpoints in the same zone as the client) and + `PreferSameNode` (prefer endpoints on the same node, fallback to same zone, then cluster-wide). + If this field is not set on the Service, the attribute SHOULD NOT be emitted. + When not set, Kubernetes distributes traffic evenly across all endpoints cluster-wide. + stability: development + - name: k8s.service.type + type: + members: + - id: cluster_ip + value: ClusterIP + brief: ClusterIP service type + stability: development + - id: node_port + value: NodePort + brief: NodePort service type + stability: development + - id: load_balancer + value: LoadBalancer + brief: LoadBalancer service type + stability: development + - id: external_name + value: ExternalName + brief: ExternalName service type + stability: development + brief: | + The type of the Kubernetes Service. + examples: + - ClusterIP + - NodePort + - LoadBalancer + requirement_level: recommended + note: | + This attribute aligns with the `type` field of the + [K8s ServiceSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec). + stability: development + - name: k8s.service.uid + type: string + brief: | + The UID of the Service. + examples: + - 275ecb36-5aa8-4c2a-9c47-d8bb681b9aff + requirement_level: recommended + stability: development - name: k8s.statefulset.annotation type: template[string] brief: | @@ -70997,6 +72541,20 @@ groups: brief: | This group defines attributes for OpenAI. attributes: + - name: openai.api.type + type: + members: + - id: chat_completions + value: chat_completions + brief: The OpenAI [Chat Completions API](https://developers.openai.com/api/reference/chat-completions/overview). + stability: development + - id: responses + value: responses + brief: The OpenAI [Responses API](https://developers.openai.com/api/reference/responses/overview). + stability: development + brief: The type of OpenAI API being used. + requirement_level: recommended + stability: development - name: openai.request.service_tier type: members: @@ -71664,6 +73222,29 @@ groups: - /bazinga/ requirement_level: recommended stability: development + - name: pprof.scope.default_sample_type + type: string + brief: | + Records the pprof's default_sample_type in the original profile. Not set if the default sample type was missing. + examples: + - cpu + requirement_level: recommended + note: | + This attribute, if present, MUST be set at the scope level (resource_profiles[].scope_profiles[].scope.attributes[]). + stability: development + - name: pprof.scope.sample_type_order + type: int[] + brief: | + Records the indexes of the sample types in the original profile. + examples: + - - 3 + - 0 + - 1 + - 2 + requirement_level: recommended + note: | + This attribute, if present, MUST be set at the scope level (resource_profiles[].scope_profiles[].scope.attributes[]). + stability: development lineage: provenance: registry_id: main @@ -72184,7 +73765,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -72194,7 +73775,7 @@ groups: - com.myservice.EchoService/unknownMethod - InvalidMethod requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.request.metadata type: template[string[]] brief: | @@ -72235,18 +73816,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -72259,7 +73840,7 @@ groups: requirement_level: recommended note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate lineage: provenance: registry_id: main @@ -72506,7 +74087,7 @@ groups: note: Use string representation of the error code on the `rpc.response.status_code` attribute. - name: rpc.jsonrpc.error_message type: string - brief: Deprecated, use span status description or `error.message` attribute on other signals. + brief: Deprecated, use the span status description when reporting JSON-RPC spans. examples: - Parse error - User already exists @@ -72514,7 +74095,7 @@ groups: stability: development deprecated: reason: uncategorized - note: Use the span status description or `error.message` attribute on other signals. + note: Use the span status description when reporting JSON-RPC spans. - name: rpc.jsonrpc.request_id type: string brief: Deprecated, use `jsonrpc.request.id` instead. @@ -73883,6 +75464,16 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + ![Development](https://img.shields.io/badge/-development-blue) + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `https://www.example.com/path?color=blue&sig=REDACTED`. stability: stable @@ -73936,6 +75527,15 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `q=OpenTelemetry&sig=REDACTED`. stability: stable @@ -74687,6 +76287,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -74730,7 +76332,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -74741,7 +76343,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -74754,11 +76356,11 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -74767,7 +76369,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -74777,7 +76381,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -74801,9 +76405,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -74924,6 +76528,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -74967,7 +76573,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -74978,7 +76584,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -74991,11 +76597,11 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -75004,7 +76610,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -75014,7 +76622,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -75056,9 +76664,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -76971,7 +78579,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -77268,7 +78876,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -80893,7 +82501,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -80958,6 +82566,16 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + ![Development](https://img.shields.io/badge/-development-blue) + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `https://www.example.com/path?color=blue&sig=REDACTED`. stability: stable @@ -82190,7 +83808,7 @@ groups: Spans representing calls to a Oracle SQL Database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). note: | `db.system.name` MUST be set to `"oracle.db"` and SHOULD be provided **at span creation time**. - stability: development + stability: release_candidate attributes: - name: db.collection.name type: string @@ -84642,7 +86260,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -84838,7 +86456,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -85072,7 +86690,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -85312,7 +86930,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -85502,7 +87120,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -85674,7 +87292,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -85867,7 +87485,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -86080,7 +87698,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -86285,7 +87903,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -86531,7 +88149,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -86852,7 +88470,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -87136,7 +88754,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -87363,7 +88981,7 @@ groups: - GetItem - PutItem requirement_level: recommended - stability: development + stability: release_candidate - name: rpc.service type: string brief: The name of the service to which a request is made, as returned by the AWS SDK. @@ -87881,6 +89499,15 @@ groups: requirement_level: conditionally_required: If provided by the application. stability: development + - name: gen_ai.agent.version + type: string + brief: The version of the GenAI agent. + examples: + - 1.0.0 + - 2025-05-01T00:00:00.000Z + requirement_level: + conditionally_required: If provided by the application. + stability: development - name: gen_ai.operation.name type: members: @@ -88115,6 +89742,15 @@ groups: - stability locally_overridden_fields: - requirement_level + gen_ai.agent.version: + source_group: registry.gen_ai + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level gen_ai.operation.name: source_group: registry.gen_ai inherited_fields: @@ -89626,6 +91262,15 @@ groups: requirement_level: conditionally_required: when available stability: development + - name: gen_ai.agent.version + type: string + brief: The version of the GenAI agent. + examples: + - 1.0.0 + - 2025-05-01T00:00:00.000Z + requirement_level: + conditionally_required: when available + stability: development - name: gen_ai.conversation.id type: string brief: The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. @@ -90201,6 +91846,15 @@ groups: - stability locally_overridden_fields: - requirement_level + gen_ai.agent.version: + source_group: registry.gen_ai + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level gen_ai.conversation.id: source_group: registry.gen_ai inherited_fields: @@ -91037,7 +92691,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -91256,6 +92910,16 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + ![Development](https://img.shields.io/badge/-development-blue) + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `https://www.example.com/path?color=blue&sig=REDACTED`. stability: stable @@ -91691,7 +93355,7 @@ groups: ![Development](https://img.shields.io/badge/-development-blue) If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or `.instrumentation/development.general.http.server`. In either case, this list MUST be a full override of the default known methods, @@ -91932,6 +93596,15 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `q=OpenTelemetry&sig=REDACTED`. stability: stable @@ -92636,7 +94309,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: server.address type: string brief: Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. @@ -93205,7 +94878,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate span_kind: server lineage: provenance: @@ -93797,6 +95470,20 @@ groups: - 180 requirement_level: recommended stability: development + - name: openai.api.type + type: + members: + - id: chat_completions + value: chat_completions + brief: The OpenAI [Chat Completions API](https://developers.openai.com/api/reference/chat-completions/overview). + stability: development + - id: responses + value: responses + brief: The OpenAI [Responses API](https://developers.openai.com/api/reference/responses/overview). + stability: development + brief: The type of OpenAI API being used. + requirement_level: recommended + stability: development - name: openai.request.service_tier type: members: @@ -94078,6 +95765,14 @@ groups: - stability locally_overridden_fields: - requirement_level + openai.api.type: + source_group: registry.openai + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level openai.request.service_tier: source_group: registry.openai inherited_fields: @@ -94145,7 +95840,7 @@ groups: **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. - stability: development + stability: release_candidate attributes: - name: error.type type: @@ -94185,6 +95880,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -94228,7 +95925,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -94239,7 +95936,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: Status code of the RPC returned by the RPC server or generated by the client @@ -94252,18 +95949,18 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate - name: rpc.system.name type: members: - id: grpc value: grpc brief: '[gRPC](https://grpc.io/)' - stability: development + stability: release_candidate - id: dubbo value: dubbo brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development + stability: release_candidate - id: connectrpc value: connectrpc brief: '[Connect RPC](https://connectrpc.com/)' @@ -94277,11 +95974,11 @@ groups: sampling_relevant: true note: | The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -94290,7 +95987,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -94300,7 +95999,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -94322,6 +96021,24 @@ groups: - requirement_level network.peer.address: source_group: registry.network + inherited_fields: + - brief + - examples + - stability + locally_overridden_fields: + - note + - requirement_level + network.peer.port: + source_group: registry.network + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + rpc.method: + source_group: registry.rpc inherited_fields: - brief - examples @@ -94329,6 +96046,562 @@ groups: - stability locally_overridden_fields: - requirement_level + - sampling_relevant + rpc.method_original: + source_group: registry.rpc + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + rpc.response.status_code: + source_group: registry.rpc + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + rpc.system.name: + source_group: registry.rpc + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level + - sampling_relevant + server.address: + source_group: registry.server + inherited_fields: + - examples + - stability + locally_overridden_fields: + - brief + - note + - requirement_level + - sampling_relevant + server.port: + source_group: registry.server + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - sampling_relevant + - id: span.rpc.call.server + type: span + brief: This span represents an incoming Remote Procedure Call (RPC). + note: | + RPC server spans SHOULD cover the entire server-side lifecycle of an RPC, + starting when the request is received and ending when the response is sent + or the RPC is terminated due to an error or cancellation. + + For streaming RPCs, the span SHOULD cover the full lifetime of the request + and/or response streams until they are closed or terminated. + + **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#name) section. + + **Span kind** MUST be `SERVER`. + + **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) + document for details on how to record span status. + stability: release_candidate + attributes: + - name: client.address + type: string + brief: Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + examples: + - client.example.com + - 10.1.2.80 + - /tmp/my.sock + requirement_level: recommended + note: | + When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. + stability: stable + - name: client.port + type: int + brief: Client port number. + examples: + - 65123 + requirement_level: recommended + note: | + When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. + stability: stable + - name: error.type + type: + members: + - id: other + value: _OTHER + brief: | + A fallback error value to be used when the instrumentation doesn't define a custom value. + stability: stable + brief: | + Describes a class of error the operation ended with. + examples: + - DEADLINE_EXCEEDED + - java.net.UnknownHostException + - '-32602' + requirement_level: + conditionally_required: If and only if the operation failed. + note: | + If the RPC fails with an error before status code is returned, + `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) + or a component-specific, low cardinality error identifier. + + If a response status code is returned and status indicates an error, + `error.type` SHOULD be set to that status code. Check system-specific conventions + for the details on which values of `rpc.response.status_code` are considered errors. + + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + If the request has completed successfully, instrumentations SHOULD NOT set + `error.type`. + stability: stable + - name: network.peer.address + type: string + brief: Peer address of the network connection - IP address or Unix domain socket name. + examples: + - 10.1.2.80 + - /tmp/my.sock + requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. + stability: stable + - name: network.peer.port + type: int + brief: Peer port number of the network connection. + examples: + - 65123 + requirement_level: + recommended: If `network.peer.address` is set. + stability: stable + - name: rpc.method + type: string + brief: The fully-qualified logical name of the method from the RPC interface perspective. + examples: + - com.example.ExampleService/exampleMethod + - EchoService/Echo + - _OTHER + requirement_level: + conditionally_required: if available. + sampling_relevant: true + note: | + The method name MAY have unbounded cardinality in edge or error cases. + + Some RPC frameworks or libraries provide a fixed set of recognized methods + for client stubs and server implementations. Instrumentations for such + frameworks MUST set this attribute to the original method name only + when the method is recognized by the framework or library. + + When the method is not recognized, for example, when the server receives + a request for a method that is not predefined on the server, or when + instrumentation is not able to reliably detect if the method is predefined, + the attribute MUST be set to `_OTHER`. In such cases, tracing + instrumentations MUST also set `rpc.method_original` attribute to + the original method value. + + If the RPC instrumentation could end up converting valid RPC methods to + `_OTHER`, then it SHOULD provide a way to configure the list of recognized + RPC methods. + + The `rpc.method` can be different from the name of any implementing + method/function. + The `code.function.name` attribute may be used to record the fully-qualified + method actually executing the call on the server side, or the + RPC client stub method on the client side. + stability: release_candidate + - name: rpc.method_original + type: string + brief: | + The original name of the method used by the client. + examples: + - com.myservice.EchoService/catchAll + - com.myservice.EchoService/unknownMethod + - InvalidMethod + requirement_level: + conditionally_required: If and only if it's different than `rpc.method`. + stability: release_candidate + - name: rpc.response.status_code + type: string + brief: Status code of the RPC returned by the RPC server or generated by the client + examples: + - OK + - DEADLINE_EXCEEDED + - '-32602' + requirement_level: + conditionally_required: if available. + note: | + Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. + Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. + stability: release_candidate + - name: rpc.system.name + type: + members: + - id: grpc + value: grpc + brief: '[gRPC](https://grpc.io/)' + stability: release_candidate + - id: dubbo + value: dubbo + brief: '[Apache Dubbo](https://dubbo.apache.org/)' + stability: release_candidate + - id: connectrpc + value: connectrpc + brief: '[Connect RPC](https://connectrpc.com/)' + stability: development + - id: jsonrpc + value: jsonrpc + brief: '[JSON-RPC](https://www.jsonrpc.org/)' + stability: development + brief: The Remote Procedure Call (RPC) system. + requirement_level: required + sampling_relevant: true + note: | + The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. + stability: release_candidate + - name: server.address + type: string + brief: | + A string identifying a group of RPC server instances request is sent to. + examples: + - example.com + - 10.1.2.80 + - /tmp/my.sock + requirement_level: + conditionally_required: If available. + sampling_relevant: true + note: | + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. + stability: stable + - name: server.port + type: int + brief: Server port number. + examples: + - 80 + - 8080 + - 443 + requirement_level: + conditionally_required: if applicable and if `server.address` is set. + sampling_relevant: true + note: | + When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + stability: stable + span_kind: server + lineage: + provenance: + registry_id: main + path: /home/weaver/source/rpc/spans.yaml + attributes: + client.address: + source_group: registry.client + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + client.port: + source_group: registry.client + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + error.type: + source_group: registry.error + inherited_fields: + - brief + - stability + locally_overridden_fields: + - examples + - note + - requirement_level + network.peer.address: + source_group: registry.network + inherited_fields: + - brief + - examples + - stability + locally_overridden_fields: + - note + - requirement_level + network.peer.port: + source_group: registry.network + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + rpc.method: + source_group: registry.rpc + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - sampling_relevant + rpc.method_original: + source_group: registry.rpc + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + rpc.response.status_code: + source_group: registry.rpc + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + rpc.system.name: + source_group: registry.rpc + inherited_fields: + - brief + - note + - stability + locally_overridden_fields: + - requirement_level + - sampling_relevant + server.address: + source_group: registry.server + inherited_fields: + - examples + - stability + locally_overridden_fields: + - brief + - note + - requirement_level + - sampling_relevant + server.port: + source_group: registry.server + inherited_fields: + - brief + - examples + - note + - stability + locally_overridden_fields: + - requirement_level + - sampling_relevant + - id: span.rpc.connect_rpc.call.client + type: span + brief: This span represents an outgoing Remote Procedure Call (RPC). + note: | + `rpc.system.name` MUST be set to `"connectrpc"` and SHOULD be provided **at span creation time.** + + **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#name) section. + + **Span kind** MUST be `CLIENT`. + + **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) + document for details on how to record span status. + stability: development + attributes: + - name: error.type + type: + members: + - id: other + value: _OTHER + brief: | + A fallback error value to be used when the instrumentation doesn't define a custom value. + stability: stable + brief: | + Describes a class of error the operation ended with. + examples: + - DEADLINE_EXCEEDED + - java.net.UnknownHostException + - '-32602' + requirement_level: + conditionally_required: If and only if the operation failed. + note: | + If the RPC fails with an error before status code is returned, + `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) + or a component-specific, low cardinality error identifier. + + If a response status code is returned and status indicates an error, + `error.type` SHOULD be set to that status code. Check system-specific conventions + for the details on which values of `rpc.response.status_code` are considered errors. + + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + If the request has completed successfully, instrumentations SHOULD NOT set + `error.type`. + stability: stable + - name: network.peer.address + type: string + brief: Peer address of the network connection - IP address or Unix domain socket name. + examples: + - 10.1.2.80 + - /tmp/my.sock + requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. + stability: stable + - name: network.peer.port + type: int + brief: Peer port number of the network connection. + examples: + - 65123 + requirement_level: + recommended: If `network.peer.address` is set. + stability: stable + - name: rpc.method + type: string + brief: The fully-qualified logical name of the method from the RPC interface perspective. + examples: + - com.example.ExampleService/exampleMethod + - EchoService/Echo + - _OTHER + requirement_level: + conditionally_required: if available. + sampling_relevant: true + note: | + The method name MAY have unbounded cardinality in edge or error cases. + + Some RPC frameworks or libraries provide a fixed set of recognized methods + for client stubs and server implementations. Instrumentations for such + frameworks MUST set this attribute to the original method name only + when the method is recognized by the framework or library. + + When the method is not recognized, for example, when the server receives + a request for a method that is not predefined on the server, or when + instrumentation is not able to reliably detect if the method is predefined, + the attribute MUST be set to `_OTHER`. In such cases, tracing + instrumentations MUST also set `rpc.method_original` attribute to + the original method value. + + If the RPC instrumentation could end up converting valid RPC methods to + `_OTHER`, then it SHOULD provide a way to configure the list of recognized + RPC methods. + + The `rpc.method` can be different from the name of any implementing + method/function. + The `code.function.name` attribute may be used to record the fully-qualified + method actually executing the call on the server side, or the + RPC client stub method on the client side. + stability: release_candidate + - name: rpc.method_original + type: string + brief: | + The original name of the method used by the client. + examples: + - com.myservice.EchoService/catchAll + - com.myservice.EchoService/unknownMethod + - InvalidMethod + requirement_level: + conditionally_required: If and only if it's different than `rpc.method`. + stability: release_candidate + - name: rpc.request.metadata + type: template[string[]] + brief: | + RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. + examples: + - - 1.2.3.4 + - 1.2.3.5 + requirement_level: opt_in + note: | + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + + For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as + `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` + stability: development + - name: rpc.response.metadata + type: template[string[]] + brief: | + RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. + examples: + - - attribute_value + requirement_level: opt_in + note: | + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + + For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as + the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_value"]` + stability: development + - name: rpc.response.status_code + type: string + brief: The [error code](https://connectrpc.com//docs/protocol/#error-codes) of the Connect response. + examples: + - OK + - DEADLINE_EXCEEDED + - '-32602' + requirement_level: + conditionally_required: if available. + note: | + All status codes except `OK` SHOULD be considered errors. + stability: release_candidate + - name: server.address + type: string + brief: The domain name or address of the Connect RPC server. + examples: + - example.com + - 10.1.2.80 + - /tmp/my.sock + requirement_level: required + sampling_relevant: true + note: | + When an IP address is provided instead of a domain name, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the provided IP address. + stability: stable + - name: server.port + type: int + brief: Server port number. + examples: + - 80 + - 8080 + - 443 + requirement_level: + conditionally_required: if available. + sampling_relevant: true + note: | + When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + stability: stable + span_kind: client + lineage: + provenance: + registry_id: main + path: /home/weaver/source/rpc/spans.yaml + attributes: + error.type: + source_group: registry.error + inherited_fields: + - brief + - stability + locally_overridden_fields: + - examples + - note + - requirement_level + network.peer.address: + source_group: registry.network + inherited_fields: + - brief + - examples + - stability + locally_overridden_fields: + - note + - requirement_level network.peer.port: source_group: registry.network inherited_fields: @@ -94357,7 +96630,7 @@ groups: - stability locally_overridden_fields: - requirement_level - rpc.response.status_code: + rpc.request.metadata: source_group: registry.rpc inherited_fields: - brief @@ -94366,15 +96639,24 @@ groups: - stability locally_overridden_fields: - requirement_level - rpc.system.name: + rpc.response.metadata: source_group: registry.rpc inherited_fields: - brief + - examples - note - stability locally_overridden_fields: - requirement_level - - sampling_relevant + rpc.response.status_code: + source_group: registry.rpc + inherited_fields: + - examples + - stability + locally_overridden_fields: + - brief + - note + - requirement_level server.address: source_group: registry.server inherited_fields: @@ -94395,16 +96677,11 @@ groups: locally_overridden_fields: - requirement_level - sampling_relevant - - id: span.rpc.call.server + - id: span.rpc.connect_rpc.call.server type: span brief: This span represents an incoming Remote Procedure Call (RPC). note: | - RPC server spans SHOULD cover the entire server-side lifecycle of an RPC, - starting when the request is received and ending when the response is sent - or the RPC is terminated due to an error or cancellation. - - For streaming RPCs, the span SHOULD cover the full lifetime of the request - and/or response streams until they are closed or terminated. + `rpc.system.name` MUST be set to `"connectrpc"` and SHOULD be provided **at span creation time.** **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#name) section. @@ -94472,6 +96749,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -94515,7 +96794,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -94526,10 +96805,39 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. + stability: release_candidate + - name: rpc.request.metadata + type: template[string[]] + brief: | + RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. + examples: + - - 1.2.3.4 + - 1.2.3.5 + requirement_level: opt_in + note: | + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + + For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as + `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` + stability: development + - name: rpc.response.metadata + type: template[string[]] + brief: | + RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. + examples: + - - attribute_value + requirement_level: opt_in + note: | + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + + For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as + the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_value"]` stability: development - name: rpc.response.status_code type: string - brief: Status code of the RPC returned by the RPC server or generated by the client + brief: The [error code](https://connectrpc.com/docs/protocol/#error-codes) of the Connect response. examples: - OK - DEADLINE_EXCEEDED @@ -94537,38 +96845,19 @@ groups: requirement_level: conditionally_required: if available. note: | - Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. - Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development - - name: rpc.system.name - type: - members: - - id: grpc - value: grpc - brief: '[gRPC](https://grpc.io/)' - stability: development - - id: dubbo - value: dubbo - brief: '[Apache Dubbo](https://dubbo.apache.org/)' - stability: development - - id: connectrpc - value: connectrpc - brief: '[Connect RPC](https://connectrpc.com/)' - stability: development - - id: jsonrpc - value: jsonrpc - brief: '[JSON-RPC](https://www.jsonrpc.org/)' - stability: development - brief: The Remote Procedure Call (RPC) system. - requirement_level: required - sampling_relevant: true - note: | - The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - stability: development + The following error codes SHOULD be considered errors: + + - `unknown` + - `deadline_exceeded` + - `unimplemented` + - `internal` + - `unavailable` + - `data_loss` + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -94577,7 +96866,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -94587,7 +96878,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -94630,9 +96921,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -94662,7 +96953,7 @@ groups: - stability locally_overridden_fields: - requirement_level - rpc.response.status_code: + rpc.request.metadata: source_group: registry.rpc inherited_fields: - brief @@ -94671,15 +96962,24 @@ groups: - stability locally_overridden_fields: - requirement_level - rpc.system.name: + rpc.response.metadata: source_group: registry.rpc inherited_fields: - brief + - examples - note - stability locally_overridden_fields: - requirement_level - - sampling_relevant + rpc.response.status_code: + source_group: registry.rpc + inherited_fields: + - examples + - stability + locally_overridden_fields: + - brief + - note + - requirement_level server.address: source_group: registry.server inherited_fields: @@ -94700,19 +97000,20 @@ groups: locally_overridden_fields: - requirement_level - sampling_relevant - - id: span.rpc.connect_rpc.call.client + - id: span.rpc.dubbo.call.client type: span brief: This span represents an outgoing Remote Procedure Call (RPC). note: | - `rpc.system.name` MUST be set to `"connectrpc"` and SHOULD be provided **at span creation time.** + `rpc.system.name` MUST be set to `"dubbo"` and SHOULD be provided **at span creation time.** **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#name) section. **Span kind** MUST be `CLIENT`. - **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) - document for details on how to record span status. - stability: development + **Span status** Refer to the [Recording Errors](/docs/general/recording-errors.md) + document for details on how to record span status. See also `rpc.response.status_code` attribute + for the details on which values classify as errors. + stability: release_candidate attributes: - name: error.type type: @@ -94752,6 +97053,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -94768,8 +97071,7 @@ groups: - com.example.ExampleService/exampleMethod - EchoService/Echo - _OTHER - requirement_level: - conditionally_required: if available. + requirement_level: required sampling_relevant: true note: | The method name MAY have unbounded cardinality in edge or error cases. @@ -94795,7 +97097,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -94806,7 +97108,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.request.metadata type: template[string[]] brief: | @@ -94838,42 +97140,65 @@ groups: stability: development - name: rpc.response.status_code type: string - brief: The [error code](https://connectrpc.com//docs/protocol/#error-codes) of the Connect response. + brief: | + The string representation of the Dubbo response status code returned by the server or generated by the client. examples: - OK - DEADLINE_EXCEEDED - - '-32602' - requirement_level: - conditionally_required: if available. + - SERVER_ERROR + requirement_level: required note: | All status codes except `OK` SHOULD be considered errors. - stability: development + + Status codes reference: + + - Dubbo2: [Dubbo2 Protocol Status Codes](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) + - Dubbo3 Triple protocol: [Triple Protocol Error Codes](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - - example.com - - 10.1.2.80 - - /tmp/my.sock + - 192.168.1.100 + - api.example.com requirement_level: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + Instrumentations SHOULD populate `server.address` (along with `server.port`) + based on the configuration used when creating the Dubbo client and + SHOULD NOT use actual network-level connection information for this purpose + to ensure low cardinality. + + The Dubbo registry address SHOULD NOT be used as `server.address`. Instead, use + the address of the actual server being called. + + - Given the target URL `dubbo://192.168.1.100:20880/com.example.DemoService`, expected attributes: + - `server.address`: `"192.168.1.100"` + - `server.port`: `20880` + - Given the target URL `tri://api.example.com:50051/com.example.GreeterService`, expected attributes: + - `server.address`: `"api.example.com"` + - `server.port`: `50051` + - Given the target URL `tri://api.example.com/com.example.GreeterService` (port not specified), expected attributes: + - `server.address`: `"api.example.com"` + - `server.port`: not set + + When the address is an IP address, instrumentations SHOULD NOT do a + reverse proxy lookup to obtain a DNS name and SHOULD set `server.address` + to the IP address provided. stability: stable - name: server.port type: int brief: Server port number. examples: - - 80 - - 8080 - - 443 + - 20880 + - 50051 requirement_level: conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. sampling_relevant: true note: | - When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + See the `server.address` for details on parsing the target string. stability: stable span_kind: client lineage: @@ -94895,9 +97220,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -94948,19 +97273,19 @@ groups: rpc.response.status_code: source_group: registry.rpc inherited_fields: - - examples - stability locally_overridden_fields: - brief + - examples - note - requirement_level server.address: source_group: registry.server inherited_fields: - - examples - stability locally_overridden_fields: - brief + - examples - note - requirement_level - sampling_relevant @@ -94968,25 +97293,26 @@ groups: source_group: registry.server inherited_fields: - brief - - examples - - note - stability locally_overridden_fields: + - examples + - note - requirement_level - sampling_relevant - - id: span.rpc.connect_rpc.call.server + - id: span.rpc.dubbo.call.server type: span brief: This span represents an incoming Remote Procedure Call (RPC). note: | - `rpc.system.name` MUST be set to `"connectrpc"` and SHOULD be provided **at span creation time.** + `rpc.system.name` MUST be set to `"dubbo"` and SHOULD be provided **at span creation time.** **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#name) section. **Span kind** MUST be `SERVER`. - **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) - document for details on how to record span status. - stability: development + **Span status** Refer to the [Recording Errors](/docs/general/recording-errors.md) + document for details on how to record span status. See also `rpc.response.status_code` attribute + for the details on which values classify as errors. + stability: release_candidate attributes: - name: client.address type: string @@ -95046,6 +97372,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -95089,7 +97417,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -95100,7 +97428,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.request.metadata type: template[string[]] brief: | @@ -95132,27 +97460,39 @@ groups: stability: development - name: rpc.response.status_code type: string - brief: The [error code](https://connectrpc.com/docs/protocol/#error-codes) of the Connect response. + brief: | + The string representation of the Dubbo response status code returned by the server. examples: - OK - - DEADLINE_EXCEEDED - - '-32602' - requirement_level: - conditionally_required: if available. + - SERVER_ERROR + - SERVER_THREADPOOL_EXHAUSTED_ERROR + requirement_level: required note: | - The following error codes SHOULD be considered errors: + For Dubbo2, the following status codes SHOULD be considered errors: - - `unknown` - - `deadline_exceeded` - - `unimplemented` - - `internal` - - `unavailable` - - `data_loss` - stability: development + - `SERVER_ERROR` + - `SERVER_THREADPOOL_EXHAUSTED_ERROR` + - `SERVER_TIMEOUT` + - `SERVICE_ERROR` + + For Dubbo3 Triple protocol, the following status codes SHOULD be considered errors: + + - `DATA_LOSS` + - `DEADLINE_EXCEEDED` + - `INTERNAL` + - `UNAVAILABLE` + - `UNIMPLEMENTED` + - `UNKNOWN` + + Status codes reference: + + - Dubbo2: [Dubbo2 Protocol Status Codes](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) + - Dubbo3 Triple protocol: [Triple Protocol Error Codes](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -95161,7 +97501,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -95214,9 +97556,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -95267,10 +97609,10 @@ groups: rpc.response.status_code: source_group: registry.rpc inherited_fields: - - examples - stability locally_overridden_fields: - brief + - examples - note - requirement_level server.address: @@ -95306,7 +97648,7 @@ groups: **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. See also `rpc.response.status_code` attribute for the details on which values classify as errors. - stability: development + stability: release_candidate attributes: - name: error.type type: @@ -95346,6 +97688,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -95388,7 +97732,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -95399,7 +97743,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.request.metadata type: template[string[]] brief: | @@ -95440,33 +97784,65 @@ groups: requirement_level: required note: | All status codes except `OK` SHOULD be considered errors. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 - /tmp/my.sock - requirement_level: - conditionally_required: If available. + requirement_level: required sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + Instrumentations SHOULD populate `server.address` (along with `server.port`) + based on the configuration used when creating the gRPC channel and + SHOULD NOT use actual network-level connection information for this purpose + to ensure low cardinality. + + Instrumentations MAY parse address and port from the gRPC target string + according to the [gRPC Name Resolution specification](https://grpc.github.io/grpc/core/md_doc_naming.html), + depending on the scheme used. Or, they MAY use gRPC client APIs that + provide this information. + + If the instrumentation cannot determine a server domain name or another + suitable low-cardinality identifier for a group of server instances + from the target string, it SHOULD set `server.address` to the entire + target string and SHOULD NOT set `server.port`. + + When the address is an IP address, instrumentations SHOULD NOT do a + reverse proxy lookup to obtain a DNS name and SHOULD set `server.address` + to the IP address provided. + + Examples: + + - Given the target string `grpc.io:50051`, expected attributes: + - `server.address`: `"grpc.io"` + - `server.port`: `50051` + - Given the target string `dns://1.2.3.4/grpc.io:50051`, expected attributes: + - `server.address`: `"grpc.io"` + - `server.port`: `50051` + - Given the target string `unix:///run/containerd/containerd.sock`, expected attributes: + - `server.address`: `"/run/containerd/containerd.sock"` + - `server.port`: not set + - Given the target string `zk://zookeeper:2181/my-server`, expected attributes: + - `server.address`: `"zk://zookeeper:2181/my-server"` + - `server.port`: not set + - Given the target string `ipv4:198.51.100.123:50051,198.51.100.124:50051`, expected attributes: + - `server.address`: `"ipv4:198.51.100.123:50051,198.51.100.124:50051"` + - `server.port`: not set stability: stable - name: server.port type: int brief: Server port number. examples: - - 80 - - 8080 - - 443 + - 50051 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: If and only if the port is available and `server.address` is set. sampling_relevant: true note: | - When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + See the `server.address` for details on parsing the target string. stability: stable span_kind: client lineage: @@ -95488,9 +97864,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -95561,10 +97937,10 @@ groups: source_group: registry.server inherited_fields: - brief - - examples - - note - stability locally_overridden_fields: + - examples + - note - requirement_level - sampling_relevant - id: span.rpc.grpc.call.server @@ -95580,7 +97956,7 @@ groups: **Span status**: refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. See also `rpc.response.status_code` attribute for the details on which values classify as errors. - stability: development + stability: release_candidate attributes: - name: client.address type: string @@ -95640,6 +98016,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -95683,7 +98061,7 @@ groups: The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -95694,7 +98072,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.request.metadata type: template[string[]] brief: | @@ -95742,11 +98120,11 @@ groups: - `INTERNAL` - `UNAVAILABLE` - `DATA_LOSS` - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -95755,7 +98133,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -95765,7 +98145,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -95808,9 +98188,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -95963,6 +98343,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -95984,7 +98366,7 @@ groups: note: | JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method_original` span attribute to the original value. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -95995,7 +98377,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: | @@ -96007,20 +98389,19 @@ groups: requirement_level: conditionally_required: when available note: All JSON RPC error codes SHOULD be considered errors. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 - /tmp/my.sock requirement_level: - conditionally_required: If available. + recommended: | + Instrumentations that have access to the transport-level information and can reliably extract domain name or another low-cardinality server address from it SHOULD set this attribute. sampling_relevant: true - note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. stability: stable - name: server.port type: int @@ -96030,7 +98411,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -96073,9 +98454,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -96230,6 +98611,8 @@ groups: - 10.1.2.80 - /tmp/my.sock requirement_level: recommended + note: | + If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. stability: stable - name: network.peer.port type: int @@ -96251,7 +98634,7 @@ groups: note: | JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases. General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to `_OTHER`, it MUST also set `rpc.method_original` span attribute to the original value. - stability: development + stability: release_candidate - name: rpc.method_original type: string brief: | @@ -96262,7 +98645,7 @@ groups: - InvalidMethod requirement_level: conditionally_required: If and only if it's different than `rpc.method`. - stability: development + stability: release_candidate - name: rpc.response.status_code type: string brief: | @@ -96274,11 +98657,11 @@ groups: requirement_level: conditionally_required: when available note: All JSON RPC error codes SHOULD be considered errors. - stability: development + stability: release_candidate - name: server.address type: string brief: | - RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + A string identifying a group of RPC server instances request is sent to. examples: - example.com - 10.1.2.80 @@ -96287,7 +98670,9 @@ groups: conditionally_required: If available. sampling_relevant: true note: | - May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. + Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. + When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. stability: stable - name: server.port type: int @@ -96297,7 +98682,7 @@ groups: - 8080 - 443 requirement_level: - conditionally_required: if `server.address` is set and if the port is supported by the network transport used for communication. + conditionally_required: if applicable and if `server.address` is set. sampling_relevant: true note: | When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. @@ -96358,9 +98743,9 @@ groups: inherited_fields: - brief - examples - - note - stability locally_overridden_fields: + - note - requirement_level network.peer.port: source_group: registry.network @@ -98129,7 +100514,7 @@ groups: note: | Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - stability: development + stability: release_candidate lineage: provenance: registry_id: main @@ -98301,6 +100686,16 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + ![Development](https://img.shields.io/badge/-development-blue) + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `https://www.example.com/path?color=blue&sig=REDACTED`. stability: stable @@ -98335,6 +100730,15 @@ groups: This list is subject to change over time. + Matching of query parameter keys against the sensitive list SHOULD be case-sensitive. + + Instrumentation MAY provide a way to override this list via declarative configuration. + If so, it SHOULD use the `sensitive_query_parameters` property + (an array of case-sensitive strings with minimum items 0) under + `.instrumentation/development.general.sanitization.url`. + This list is a full override of the default sensitive query parameter keys, + it is not a list of keys in addition to the defaults. + When a query string value is redacted, the query string key SHOULD still be preserved, e.g. `q=OpenTelemetry&sig=REDACTED`. stability: stable diff --git a/src/platform/packages/shared/kbn-otel-semantic-conventions/src/generated/resolved-semconv.ts b/src/platform/packages/shared/kbn-otel-semantic-conventions/src/generated/resolved-semconv.ts index 9ca3d32ec119d..c95a274e37c59 100644 --- a/src/platform/packages/shared/kbn-otel-semantic-conventions/src/generated/resolved-semconv.ts +++ b/src/platform/packages/shared/kbn-otel-semantic-conventions/src/generated/resolved-semconv.ts @@ -12,14 +12,14 @@ * * This file is auto-generated. Do not edit manually. * Sources: resolved-semconv.yaml + hardcoded OTLP mappings - * Registry groups: 142 - * Metric groups: 497 + * Registry groups: 143 + * Metric groups: 502 * Hardcoded fields: 34 - * Total fields: 1196 + * Total fields: 1216 * * @internal * - * WARNING: This object contains 1196+ field definitions (~50KB+ minified). + * WARNING: This object contains 1216+ field definitions (~50KB+ minified). * Direct import will significantly increase client bundle size. * * RECOMMENDED USAGE: @@ -1380,12 +1380,6 @@ export const semconvFlat = { type: 'keyword', example: 'QdH5CAWJgqVT4rOr0qtumf', }, - 'error.message': { - name: 'error.message', - description: 'A message providing more detail about an error in human-readable form.', - type: 'keyword', - example: 'Unexpected input type: string', - }, 'error.type': { name: 'error.type', description: 'Describes a class of error the operation ended with.', @@ -1520,6 +1514,13 @@ export const semconvFlat = { type: 'keyword', example: '5157782b-2203-4c80-a857-dbbd5e7761db', }, + 'feature_flag.error.message': { + name: 'feature_flag.error.message', + description: + 'A message providing more detail about an error that occurred during feature flag evaluation in human-readable form.', + type: 'keyword', + example: 'Unexpected input type: string', + }, 'feature_flag.key': { name: 'feature_flag.key', description: 'The lookup key of the feature flag.', @@ -1850,6 +1851,12 @@ export const semconvFlat = { type: 'keyword', example: 'Math Tutor', }, + 'gen_ai.agent.version': { + name: 'gen_ai.agent.version', + description: 'The version of the GenAI agent.', + type: 'keyword', + example: '1.0.0', + }, 'gen_ai.conversation.id': { name: 'gen_ai.conversation.id', description: @@ -2966,6 +2973,75 @@ export const semconvFlat = { type: 'keyword', example: '275ecb36-5aa8-4c2a-9c47-d8bb681b9aff', }, + 'k8s.service.annotation': { + name: 'k8s.service.annotation', + description: + 'The annotation placed on the Service, the `` being the annotation name, the value being the annotation value, even if the value is empty.', + type: 'keyword', + example: 'true', + }, + 'k8s.service.endpoint.address_type': { + name: 'k8s.service.endpoint.address_type', + description: 'The address type of the service endpoint.', + type: 'keyword', + example: 'IPv4', + }, + 'k8s.service.endpoint.condition': { + name: 'k8s.service.endpoint.condition', + description: 'The condition of the service endpoint.', + type: 'keyword', + example: 'ready', + }, + 'k8s.service.endpoint.zone': { + name: 'k8s.service.endpoint.zone', + description: 'The zone of the service endpoint.', + type: 'keyword', + example: 'us-east-1a', + }, + 'k8s.service.label': { + name: 'k8s.service.label', + description: + 'The label placed on the Service, the `` being the label name, the value being the label value, even if the value is empty.', + type: 'keyword', + example: 'my-service', + }, + 'k8s.service.name': { + name: 'k8s.service.name', + description: 'The name of the Service.', + type: 'keyword', + example: 'my-service', + }, + 'k8s.service.publish_not_ready_addresses': { + name: 'k8s.service.publish_not_ready_addresses', + description: 'Whether the Service publishes not-ready endpoints.', + type: 'boolean', + example: 'true', + }, + 'k8s.service.selector': { + name: 'k8s.service.selector', + description: + 'The selector key-value pair placed on the Service, the `` being the selector key, the value being the selector value.', + type: 'keyword', + example: 'my-app', + }, + 'k8s.service.traffic_distribution': { + name: 'k8s.service.traffic_distribution', + description: 'The traffic distribution policy for the Service.', + type: 'keyword', + example: 'PreferSameZone', + }, + 'k8s.service.type': { + name: 'k8s.service.type', + description: 'The type of the Kubernetes Service.', + type: 'keyword', + example: 'ClusterIP', + }, + 'k8s.service.uid': { + name: 'k8s.service.uid', + description: 'The UID of the Service.', + type: 'keyword', + example: '275ecb36-5aa8-4c2a-9c47-d8bb681b9aff', + }, 'k8s.statefulset.annotation': { name: 'k8s.statefulset.annotation', description: @@ -3826,6 +3902,18 @@ export const semconvFlat = { description: 'GenAI operation duration.', type: 'double', }, + 'metrics.gen_ai.client.operation.time_per_output_chunk': { + name: 'metrics.gen_ai.client.operation.time_per_output_chunk', + description: + 'Time per output chunk, recorded for each chunk received after the first one, measured as the time elapsed from the end of the previous chunk to the end of the current chunk.', + type: 'double', + }, + 'metrics.gen_ai.client.operation.time_to_first_chunk': { + name: 'metrics.gen_ai.client.operation.time_to_first_chunk', + description: + 'Time to receive the first chunk, measured from when the client issues the generation request to when the first chunk is received in the response stream.', + type: 'double', + }, 'metrics.gen_ai.client.token.usage': { name: 'metrics.gen_ai.client.token.usage', description: 'Number of input and output tokens used.', @@ -4207,6 +4295,11 @@ export const semconvFlat = { description: 'Number of open file descriptors as reported by the JVM.', type: 'double', }, + 'metrics.jvm.file_descriptor.limit': { + name: 'metrics.jvm.file_descriptor.limit', + description: 'Measure of max open file descriptors as reported by the JVM.', + type: 'double', + }, 'metrics.jvm.gc.duration': { name: 'metrics.jvm.gc.duration', description: 'Duration of JVM garbage collection actions.', @@ -4775,6 +4868,17 @@ export const semconvFlat = { 'The storage requests in a specific namespace. The value represents the current observed total usage of the resource in the namespace.', type: 'double', }, + 'metrics.k8s.service.endpoint.count': { + name: 'metrics.k8s.service.endpoint.count', + description: 'Number of endpoints for a service by condition and address type.', + type: 'double', + }, + 'metrics.k8s.service.load_balancer.ingress.count': { + name: 'metrics.k8s.service.load_balancer.ingress.count', + description: + 'Number of load balancer ingress points (external IPs/hostnames) assigned to the service.', + type: 'double', + }, 'metrics.k8s.statefulset.pod.current': { name: 'metrics.k8s.statefulset.pod.current', description: @@ -5706,6 +5810,11 @@ export const semconvFlat = { description: 'ONC/Sun RPC program version.', type: 'long', }, + 'openai.api.type': { + name: 'openai.api.type', + description: 'The type of OpenAI API being used.', + type: 'keyword', + }, 'openai.request.service_tier': { name: 'openai.request.service_tier', description: 'The service tier requested. May be a specific tier, default, or auto.', @@ -5929,6 +6038,19 @@ export const semconvFlat = { type: 'keyword', example: '/bazinga/', }, + 'pprof.scope.default_sample_type': { + name: 'pprof.scope.default_sample_type', + description: + "Records the pprof's default_sample_type in the original profile. Not set if the default sample type was missing.", + type: 'keyword', + example: 'cpu', + }, + 'pprof.scope.sample_type_order': { + name: 'pprof.scope.sample_type_order', + description: 'Records the indexes of the sample types in the original profile.', + type: 'long', + example: '3,0,1,2', + }, 'process.args_count': { name: 'process.args_count', description: 'Length of the process.command_args array', @@ -6273,7 +6395,7 @@ export const semconvFlat = { }, 'server.address': { name: 'server.address', - description: 'RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html).', + description: 'A string identifying a group of RPC server instances request is sent to.', type: 'keyword', example: 'example.com', },