diff --git a/.gitignore b/.gitignore index 18f2c1c9..a5dffafe 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,9 @@ just.zsh .vscode/ .devcontainer/ +# Visual Studio +.vs/ + # Emacs *~ \#*\# diff --git a/crates/weaver_forge/data/exception.yaml b/crates/weaver_forge/data/exception.yaml new file mode 100644 index 00000000..70dea3d5 --- /dev/null +++ b/crates/weaver_forge/data/exception.yaml @@ -0,0 +1,54 @@ +groups: + - id: registry.exception + type: attribute_group + prefix: exception + brief: > + This document defines the shared attributes used to + report a single exception associated with a span or log. + attributes: + - id: type + type: string + stability: stable + 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"] + - id: message + type: string + stability: stable + brief: The exception message. + examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] + - id: stacktrace + type: string + stability: stable + 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)' + - id: escaped + type: boolean + stability: stable + brief: > + SHOULD be set to true if the exception event is recorded at a point where + it is known that the exception is escaping the scope of the span. + note: |- + An exception is considered to have escaped (or left) the scope of a span, + if that span is ended while the exception is still logically "in flight". + This may be actually "in flight" in some languages (e.g. if the exception + is passed to a Context manager's `__exit__` method in Python) but will + usually be caught at the point of recording the exception in most languages. + + It is usually not possible to determine at the point where an exception is thrown + whether it will escape the scope of a span. + However, it is trivial to know that an exception + will escape, if one checks for an active exception just before ending the span, + as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + + It follows that an exception may still escape the scope of the span + even if the `exception.escaped` attribute was not set or set to false, + since the event might have been recorded at a time where it was not + clear whether the exception will escape. diff --git a/crates/weaver_forge/data/mobile-events.yaml b/crates/weaver_forge/data/mobile-events.yaml index 9f0af378..b1b219d5 100644 --- a/crates/weaver_forge/data/mobile-events.yaml +++ b/crates/weaver_forge/data/mobile-events.yaml @@ -1,74 +1,74 @@ groups: - - id: ios.lifecycle.events + - id: device.app.lifecycle + stability: experimental type: event - prefix: ios name: device.app.lifecycle brief: > - This event represents an occurrence of a lifecycle transition on the iOS platform. - attributes: - - id: state - stability: experimental - requirement_level: "required" - note: > - The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), - and from which the `OS terminology` column values are derived. - brief: > - This attribute represents the state the application has transitioned into at the occurrence of the event. - type: - allow_custom_values: false - members: - - id: active - value: 'active' - brief: > - The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. - - id: inactive - value: 'inactive' - brief: > - The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. - - id: background - value: 'background' - brief: > - The app is now in the background. - This value is associated with UIKit notification `applicationDidEnterBackground`. - - id: foreground - value: 'foreground' - brief: > - The app is now in the foreground. - This value is associated with UIKit notification `applicationWillEnterForeground`. - - id: terminate - value: 'terminate' - brief: > - The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. - - id: android.lifecycle.events - type: event - prefix: android - name: device.app.lifecycle - brief: > - This event represents an occurrence of a lifecycle transition on the Android platform. - attributes: - - id: state - stability: experimental - requirement_level: required - brief: > - This attribute represents the state the application has transitioned into at the occurrence of the event. - note: > - The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), - and from which the `OS identifiers` are derived. - type: - allow_custom_values: false - members: - - id: created - value: 'created' - brief: > - Any time before Activity.onResume() or, if the app has no Activity, Context.startService() - has been called in the app for the first time. - - id: background - value: 'background' - brief: > - Any time after Activity.onPause() or, if the app has no Activity, - Context.stopService() has been called when the app was in the foreground state. - - id: foreground - value: 'foreground' - brief: > - Any time after Activity.onResume() or, if the app has no Activity, - Context.startService() has been called when the app was in either the created or background states. \ No newline at end of file + This event represents an occurrence of a lifecycle transition on Android or iOS platform. + note: > + This event identifies the fields that are common to all lifecycle events for android and iOS using + the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are + mutually exclusive. + body: + fields: + - id: ios.state + stability: experimental + requirement_level: + conditionally_required: if and only if `os.name` is `ios` + note: > + The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), + and from which the `OS terminology` column values are derived. + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + type: + allow_custom_values: false + members: + - id: active + value: 'active' + brief: > + The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + - id: inactive + value: 'inactive' + brief: > + The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + - id: background + value: 'background' + brief: > + The app is now in the background. + This value is associated with UIKit notification `applicationDidEnterBackground`. + - id: foreground + value: 'foreground' + brief: > + The app is now in the foreground. + This value is associated with UIKit notification `applicationWillEnterForeground`. + - id: terminate + value: 'terminate' + brief: > + The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + - id: android.state + stability: experimental + requirement_level: + conditionally_required: if and only if `os.name` is `android` + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + note: > + The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), + and from which the `OS identifiers` are derived. + type: + allow_custom_values: false + members: + - id: created + value: 'created' + brief: > + Any time before Activity.onResume() or, if the app has no Activity, Context.startService() + has been called in the app for the first time. + - id: background + value: 'background' + brief: > + Any time after Activity.onPause() or, if the app has no Activity, + Context.stopService() has been called when the app was in the foreground state. + - id: foreground + value: 'foreground' + brief: > + Any time after Activity.onResume() or, if the app has no Activity, + Context.startService() has been called when the app was in either the created or background states. \ No newline at end of file diff --git a/crates/weaver_forge/data/registry-client.yaml b/crates/weaver_forge/data/registry-client.yaml new file mode 100644 index 00000000..3b17ed8b --- /dev/null +++ b/crates/weaver_forge/data/registry-client.yaml @@ -0,0 +1,28 @@ +groups: + - id: registry.client + prefix: client + type: attribute_group + brief: > + These attributes may be used to describe the client in a connection-based network interaction + where there is one side that initiates the connection (the client is the side that initiates the connection). + This covers all TCP network interactions since TCP is connection-based and one side initiates the + connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the + protocol / API doesn't expose a clear notion of client and server). + This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + attributes: + - id: address + stability: stable + type: string + brief: "Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + 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. + examples: ['client.example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + stability: stable + type: int + brief: Client port number. + examples: [65123] + 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. diff --git a/crates/weaver_forge/data/registry-gen_ai.yaml b/crates/weaver_forge/data/registry-gen_ai.yaml new file mode 100644 index 00000000..ce6755a1 --- /dev/null +++ b/crates/weaver_forge/data/registry-gen_ai.yaml @@ -0,0 +1,148 @@ +groups: + - id: registry.gen_ai + prefix: gen_ai + type: attribute_group + brief: > + This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. + attributes: + - id: system + stability: experimental + type: + members: + - id: openai + stability: experimental + value: "openai" + brief: 'OpenAI' + - id: vertex_ai + stability: experimental + value: "vertex_ai" + brief: 'Vertex AI' + - id: anthropic + stability: experimental + value: "anthropic" + brief: 'Anthropic' + - id: cohere + stability: experimental + value: "cohere" + brief: 'Cohere' + brief: The Generative AI product as identified by the client or server instrumentation. + note: | + The `gen_ai.system` describes a family of GenAI models with specific model identified + by `gen_ai.request.model` and `gen_ai.response.model` attributes. + + The actual GenAI product may differ from the one identified by the client. + For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` + is set to `openai` based on the instrumentation's best knowledge. + + For custom model, a custom friendly name SHOULD be used. + If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + examples: 'openai' + - id: request.model + stability: experimental + type: string + brief: The name of the GenAI model a request is being made to. + examples: 'gpt-4' + - id: request.max_tokens + stability: experimental + type: int + brief: The maximum number of tokens the model generates for a request. + examples: [100] + - id: request.temperature + stability: experimental + type: double + brief: The temperature setting for the GenAI request. + examples: [0.0] + - id: request.top_p + stability: experimental + type: double + brief: The top_p sampling setting for the GenAI request. + examples: [1.0] + tag: llm-generic-request + - id: request.top_k + stability: experimental + type: double + brief: The top_k sampling setting for the GenAI request. + examples: [1.0] + - id: request.stop_sequences + stability: experimental + type: string[] + brief: List of sequences that the model will use to stop generating further tokens. + examples: ['forest', 'lived'] + - id: request.frequency_penalty + stability: experimental + type: double + brief: The frequency penalty setting for the GenAI request. + examples: [0.1] + - id: request.presence_penalty + stability: experimental + type: double + brief: The presence penalty setting for the GenAI request. + examples: [0.1] + - id: response.id + stability: experimental + type: string + brief: The unique identifier for the completion. + examples: ['chatcmpl-123'] + - id: response.model + stability: experimental + type: string + brief: The name of the model that generated the response. + examples: ['gpt-4-0613'] + - id: response.finish_reasons + stability: experimental + type: string[] + brief: Array of reasons the model stopped generating tokens, corresponding to each generation received. + examples: ['stop'] + - id: usage.input_tokens + stability: experimental + type: int + brief: The number of tokens used in the GenAI input (prompt). + examples: [100] + - id: usage.output_tokens + stability: experimental + type: int + brief: The number of tokens used in the GenAI response (completion). + examples: [180] + - id: token.type + stability: experimental + type: + members: + - id: input + stability: experimental + value: "input" + brief: 'Input tokens (prompt, input, etc.)' + - id: completion + stability: experimental + value: "output" + brief: 'Output tokens (completion, response, etc.)' + brief: The type of token being counted. + examples: ['input', 'output'] + - id: prompt + stability: experimental + type: string + brief: The full prompt sent to the GenAI model. + note: It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + examples: ["[{'role': 'user', 'content': 'What is the capital of France?'}]"] + - id: completion + stability: experimental + type: string + brief: The full response received from the GenAI model. + note: It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + examples: ["[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]"] + - id: operation.name + stability: experimental + type: + members: + - id: chat + value: "chat" + brief: 'Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)' + stability: experimental + - 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: experimental + brief: The name of the operation being performed. + 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. diff --git a/crates/weaver_forge/data/registry-rpc.yaml b/crates/weaver_forge/data/registry-rpc.yaml new file mode 100644 index 00000000..d1e0aa05 --- /dev/null +++ b/crates/weaver_forge/data/registry-rpc.yaml @@ -0,0 +1,265 @@ +groups: + - id: registry.rpc + prefix: rpc + type: attribute_group + brief: 'This document defines attributes for remote procedure calls.' + attributes: + - id: connect_rpc.error_code + type: + members: + - id: cancelled + value: cancelled + stability: experimental + - id: unknown + value: unknown + stability: experimental + - id: invalid_argument + value: invalid_argument + stability: experimental + - id: deadline_exceeded + value: deadline_exceeded + stability: experimental + - id: not_found + value: not_found + stability: experimental + - id: already_exists + value: already_exists + stability: experimental + - id: permission_denied + value: permission_denied + stability: experimental + - id: resource_exhausted + value: resource_exhausted + stability: experimental + - id: failed_precondition + value: failed_precondition + stability: experimental + - id: aborted + value: aborted + stability: experimental + - id: out_of_range + value: out_of_range + stability: experimental + - id: unimplemented + value: unimplemented + stability: experimental + - id: internal + value: internal + stability: experimental + - id: unavailable + value: unavailable + stability: experimental + - id: data_loss + value: data_loss + stability: experimental + - id: unauthenticated + value: unauthenticated + stability: experimental + stability: experimental + brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - id: connect_rpc.request.metadata + type: template[string[]] + stability: experimental + brief: > + Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: connect_rpc.response.metadata + type: template[string[]] + stability: experimental + brief: > + Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: grpc.status_code + type: + members: + - id: ok + brief: OK + stability: experimental + value: 0 + - id: cancelled + brief: CANCELLED + stability: experimental + value: 1 + - id: unknown + brief: UNKNOWN + stability: experimental + value: 2 + - id: invalid_argument + brief: INVALID_ARGUMENT + stability: experimental + value: 3 + - id: deadline_exceeded + brief: DEADLINE_EXCEEDED + stability: experimental + value: 4 + - id: not_found + brief: NOT_FOUND + stability: experimental + value: 5 + - id: already_exists + brief: ALREADY_EXISTS + stability: experimental + value: 6 + - id: permission_denied + brief: PERMISSION_DENIED + stability: experimental + value: 7 + - id: resource_exhausted + brief: RESOURCE_EXHAUSTED + stability: experimental + value: 8 + - id: failed_precondition + brief: FAILED_PRECONDITION + stability: experimental + value: 9 + - id: aborted + brief: ABORTED + stability: experimental + value: 10 + - id: out_of_range + brief: OUT_OF_RANGE + stability: experimental + value: 11 + - id: unimplemented + brief: UNIMPLEMENTED + stability: experimental + value: 12 + - id: internal + brief: INTERNAL + stability: experimental + value: 13 + - id: unavailable + brief: UNAVAILABLE + stability: experimental + value: 14 + - id: data_loss + brief: DATA_LOSS + stability: experimental + value: 15 + - id: unauthenticated + brief: UNAUTHENTICATED + stability: experimental + value: 16 + stability: experimental + brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: grpc.request.metadata + type: template[string[]] + stability: experimental + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: grpc.response.metadata + type: template[string[]] + stability: experimental + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: jsonrpc.error_code + type: int + stability: experimental + brief: "`error.code` property of response if it is an error response." + examples: [-32700, 100] + - id: jsonrpc.error_message + type: string + stability: experimental + brief: "`error.message` property of response if it is an error response." + examples: ['Parse error', 'User already exists'] + - id: jsonrpc.request_id + type: string + stability: experimental + brief: > + `id` property of request or response. + Since protocol allows id to be int, string, `null` or missing (for notifications), + value is expected to be cast to string for simplicity. + Use empty string in case of `null` value. Omit entirely if this is a notification. + examples: ['10', 'request-7', ''] + - id: jsonrpc.version + type: string + stability: experimental + brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted." + examples: ['2.0', '1.0'] + - id: method + type: string + stability: experimental + brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' + note: > + This is the logical name of the method from the RPC interface perspective, + which can be different from the name of any implementing method/function. + The `code.function` attribute may be used to store the latter + (e.g., method actually executing the call on the server side, + RPC client stub method on the client side). + examples: "exampleMethod" + - id: service + type: string + stability: experimental + brief: 'The full (logical) name of the service being called, including its package name, if applicable.' + note: > + This is the logical name of the service from the RPC interface perspective, + which can be different from the name of any implementing class. + The `code.namespace` attribute may be used to store the latter + (despite the attribute name, it may include a class name; + e.g., class with method actually executing the call on the server side, + RPC client stub class on the client side). + examples: "myservice.EchoService" + - id: system + brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' + type: + allow_custom_values: true + members: + - id: grpc + value: 'grpc' + brief: 'gRPC' + stability: experimental + - id: java_rmi + value: 'java_rmi' + brief: 'Java RMI' + stability: experimental + - id: dotnet_wcf + value: 'dotnet_wcf' + brief: '.NET WCF' + stability: experimental + - id: apache_dubbo + value: 'apache_dubbo' + brief: 'Apache Dubbo' + stability: experimental + - id: connect_rpc + value: 'connect_rpc' + brief: 'Connect RPC' + stability: experimental + stability: experimental + - id: message.type + type: + members: + - id: sent + value: "SENT" + stability: experimental + - id: received + value: "RECEIVED" + stability: experimental + stability: experimental + brief: "Whether this is a received or sent message." + - id: message.id + type: int + stability: experimental + brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." + note: "This way we guarantee that the values will be consistent between different implementations." + - id: message.compressed_size + type: int + stability: experimental + brief: "Compressed size of the message in bytes." + - id: message.uncompressed_size + type: int + stability: experimental + brief: "Uncompressed size of the message in bytes." diff --git a/crates/weaver_forge/data/trace-exception.yaml b/crates/weaver_forge/data/trace-exception.yaml new file mode 100644 index 00000000..32c53f4b --- /dev/null +++ b/crates/weaver_forge/data/trace-exception.yaml @@ -0,0 +1,16 @@ +groups: + - id: trace-exception + prefix: exception + type: event + brief: > + This document defines the attributes used to + report a single exception associated with a span. + attributes: + - ref: exception.type + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + - ref: exception.message + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + - ref: exception.stacktrace + - ref: exception.escaped diff --git a/crates/weaver_forge/data/trace-feature-flag.yaml b/crates/weaver_forge/data/trace-feature-flag.yaml new file mode 100644 index 00000000..fa4c8816 --- /dev/null +++ b/crates/weaver_forge/data/trace-feature-flag.yaml @@ -0,0 +1,34 @@ +groups: + - id: feature_flag + prefix: feature_flag + type: event + brief: > + This semantic convention defines the attributes used to represent a + feature flag evaluation as an event. + attributes: + - id: key + type: string + requirement_level: required + brief: The unique identifier of the feature flag. + examples: ["logo-color"] + - id: provider_name + type: string + requirement_level: recommended + brief: The name of the service provider that performs the flag evaluation. + examples: ["Flag Manager"] + - id: variant + type: string + requirement_level: recommended + examples: ["red", "true", "on"] + brief: > + SHOULD be a semantic identifier for a value. If one is unavailable, a + stringified version of the value can be used. + note: |- + A semantic identifier, commonly referred to as a variant, provides a means + for referring to a value without including the value itself. This can + provide additional context for understanding the meaning behind a value. + For example, the variant `red` maybe be used for the value `#c05543`. + + A stringified version of the value can be used in situations where a + semantic identifier is unavailable. String representation of the value + should be determined by the implementer. \ No newline at end of file diff --git a/crates/weaver_forge/data/trace-gen-ai.yaml b/crates/weaver_forge/data/trace-gen-ai.yaml new file mode 100644 index 00000000..d036c197 --- /dev/null +++ b/crates/weaver_forge/data/trace-gen-ai.yaml @@ -0,0 +1,73 @@ +groups: + - id: trace.gen_ai.client + type: span + brief: > + Describes GenAI operation span. + attributes: + - ref: gen_ai.system + requirement_level: required + - ref: gen_ai.request.model + requirement_level: required + note: > + The name of the GenAI model a request is being made to. If the model is supplied by a vendor, + then the value must be the exact name of the model requested. If the model is a fine-tuned + custom model, the value should have a more specific name than the base model that's been fine-tuned. + - ref: gen_ai.operation.name + requirement_level: required + - ref: gen_ai.request.max_tokens + requirement_level: recommended + - ref: gen_ai.request.temperature + requirement_level: recommended + - ref: gen_ai.request.top_p + requirement_level: recommended + - ref: gen_ai.request.top_k + requirement_level: recommended + - ref: gen_ai.request.stop_sequences + requirement_level: recommended + - ref: gen_ai.request.frequency_penalty + requirement_level: recommended + - ref: gen_ai.request.presence_penalty + requirement_level: recommended + - ref: gen_ai.response.id + requirement_level: recommended + - ref: gen_ai.response.model + requirement_level: recommended + note: > + If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, + then the value must be the exact name of the model actually used. If the model is a + fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + - ref: gen_ai.response.finish_reasons + requirement_level: recommended + - ref: gen_ai.usage.input_tokens + requirement_level: recommended + - ref: gen_ai.usage.output_tokens + requirement_level: recommended + events: + - gen_ai.content.prompt + - gen_ai.content.completion + + - id: gen_ai.content.prompt + name: gen_ai.content.prompt + type: event + brief: > + In the lifetime of an GenAI span, events for prompts sent and completions received + may be created, depending on the configuration of the instrumentation. + attributes: + - ref: gen_ai.prompt + requirement_level: + conditionally_required: if and only if corresponding event is enabled + note: > + It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + + - id: gen_ai.content.completion + name: gen_ai.content.completion + type: event + brief: > + In the lifetime of an GenAI span, events for prompts sent and completions received + may be created, depending on the configuration of the instrumentation. + attributes: + - ref: gen_ai.completion + requirement_level: + conditionally_required: if and only if corresponding event is enabled + note: > + It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) diff --git a/crates/weaver_forge/data/trace-rpc.yaml b/crates/weaver_forge/data/trace-rpc.yaml new file mode 100644 index 00000000..d578c6ba --- /dev/null +++ b/crates/weaver_forge/data/trace-rpc.yaml @@ -0,0 +1,131 @@ +groups: + - id: rpc + prefix: rpc + type: span + brief: 'This document defines semantic conventions for remote procedure calls.' + events: [rpc.message] + attributes: + - ref: rpc.system + requirement_level: required + - ref: rpc.service + requirement_level: recommended + - ref: rpc.method + requirement_level: recommended + - ref: network.transport + requirement_level: recommended + - ref: network.type + requirement_level: recommended + - ref: server.address + requirement_level: required + brief: > + RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + 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. + - ref: server.port + requirement_level: + conditionally_required: if the port is supported by the network transport used for communication. + + - id: rpc.client + type: span + brief: 'This document defines semantic conventions for remote procedure call client spans.' + extends: rpc + attributes: + - ref: network.peer.address + requirement_level: recommended + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + + - id: rpc.server + type: span + extends: rpc + span_kind: server + brief: 'Semantic Convention for RPC server spans' + attributes: + - ref: client.address + requirement_level: recommended + - ref: client.port + requirement_level: recommended + - ref: network.peer.address + requirement_level: recommended + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + - ref: network.transport + requirement_level: recommended + - ref: network.type + requirement_level: recommended + + - id: rpc.grpc + type: span + extends: rpc + brief: 'Tech-specific attributes for gRPC.' + attributes: + - ref: rpc.grpc.status_code + tag: grpc-tech-specific + requirement_level: required + - ref: rpc.grpc.request.metadata + tag: grpc-tech-specific + requirement_level: opt_in + - ref: rpc.grpc.response.metadata + tag: grpc-tech-specific + requirement_level: opt_in + + - id: rpc.jsonrpc + prefix: rpc.jsonrpc + type: span + extends: rpc + brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' + attributes: + - ref: rpc.jsonrpc.version + tag: jsonrpc-tech-specific + requirement_level: + conditionally_required: If other than the default version (`1.0`) + - ref: rpc.jsonrpc.request_id + tag: jsonrpc-tech-specific + requirement_level: recommended + - ref: rpc.jsonrpc.error_code + tag: jsonrpc-tech-specific + requirement_level: + conditionally_required: If response is not successful. + - ref: rpc.jsonrpc.error_message + tag: jsonrpc-tech-specific + requirement_level: recommended + - ref: rpc.method + tag: jsonrpc-tech-specific + requirement_level: required + note: > + This is always required for jsonrpc. See the note in the general + RPC conventions for more information. + + - id: rpc.message + prefix: rpc.message + type: event + brief: "RPC received/sent message." + attributes: + - ref: rpc.message.type + requirement_level: recommended + - ref: rpc.message.id + requirement_level: recommended + - ref: rpc.message.compressed_size + requirement_level: recommended + - ref: rpc.message.uncompressed_size + requirement_level: recommended + + - id: rpc.connect_rpc + type: span + extends: rpc + brief: 'Tech-specific attributes for Connect RPC.' + attributes: + - ref: rpc.connect_rpc.error_code + tag: connect_rpc-tech-specific + requirement_level: + conditionally_required: If response is not successful and if error code available. + - ref: rpc.connect_rpc.request.metadata + tag: connect_rpc-tech-specific + requirement_level: opt_in + - ref: rpc.connect_rpc.response.metadata + tag: connect_rpc-tech-specific + requirement_level: opt_in diff --git a/crates/weaver_forge/expected_output/test/attribute_group/registry_client.md b/crates/weaver_forge/expected_output/test/attribute_group/registry_client.md new file mode 100644 index 00000000..ebe6ac3a --- /dev/null +++ b/crates/weaver_forge/expected_output/test/attribute_group/registry_client.md @@ -0,0 +1,47 @@ +## Group `registry_client` (attribute_group) + +### Brief + +These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +prefix: client + +### Attributes + + +#### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/attribute_group/registry_exception.md b/crates/weaver_forge/expected_output/test/attribute_group/registry_exception.md new file mode 100644 index 00000000..f5181ff0 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/attribute_group/registry_exception.md @@ -0,0 +1,85 @@ +## Group `registry_exception` (attribute_group) + +### Brief + +This document defines the shared attributes used to report a single exception associated with a span or log. + +prefix: exception + +### Attributes + + +#### Attribute `exception.type` + +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. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +#### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + +#### Attribute `exception.stacktrace` + +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. + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +#### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/attribute_group/registry_gen_ai.md b/crates/weaver_forge/expected_output/test/attribute_group/registry_gen_ai.md new file mode 100644 index 00000000..3f77243c --- /dev/null +++ b/crates/weaver_forge/expected_output/test/attribute_group/registry_gen_ai.md @@ -0,0 +1,294 @@ +## Group `registry_gen_ai` (attribute_group) + +### Brief + +This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. + +prefix: gen_ai + +### Attributes + + +#### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +- Requirement Level: Recommended + +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai + +- Stability: Experimental + + +#### Attribute `gen_ai.request.model` + +The name of the GenAI model a request is being made to. + + +- Requirement Level: Recommended + +- Type: string +- Examples: gpt-4 + +- Stability: Experimental + + +#### Attribute `gen_ai.request.max_tokens` + +The maximum number of tokens the model generates for a request. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.temperature` + +The temperature setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_p` + +The top_p sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Tag: llm-generic-request + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_k` + +The top_k sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.stop_sequences` + +List of sequences that the model will use to stop generating further tokens. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "forest", + "lived", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.frequency_penalty` + +The frequency penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.presence_penalty` + +The presence penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.id` + +The unique identifier for the completion. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.model` + +The name of the model that generated the response. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.finish_reasons` + +Array of reasons the model stopped generating tokens, corresponding to each generation received. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.input_tokens` + +The number of tokens used in the GenAI input (prompt). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.output_tokens` + +The number of tokens used in the GenAI response (completion). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.token.type` + +The type of token being counted. + + +- Requirement Level: Recommended + +- Type: Enum [input, output] +- Examples: [ + "input", + "output", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.completion` + +The full response received from the GenAI model. + + +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Recommended + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/attribute_group/registry_rpc.md b/crates/weaver_forge/expected_output/test/attribute_group/registry_rpc.md new file mode 100644 index 00000000..2b313dce --- /dev/null +++ b/crates/weaver_forge/expected_output/test/attribute_group/registry_rpc.md @@ -0,0 +1,260 @@ +## Group `registry_rpc` (attribute_group) + +### Brief + +This document defines attributes for remote procedure calls. + +prefix: rpc + +### Attributes + + +#### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Recommended + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Recommended + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Recommended + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +#### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/attribute_groups.md b/crates/weaver_forge/expected_output/test/attribute_groups.md index 38d2cf9c..3af22d39 100644 --- a/crates/weaver_forge/expected_output/test/attribute_groups.md +++ b/crates/weaver_forge/expected_output/test/attribute_groups.md @@ -4,6 +4,95 @@ - one - two - three +## Group `registry.exception` (attribute_group) + +### Brief + +This document defines the shared attributes used to report a single exception associated with a span or log. + +prefix: exception + +### Attributes + + +#### Attribute `exception.type` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +#### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + +#### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +#### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + + ## Group `attributes.jvm.memory` (attribute_group) ### Brief @@ -51,6 +140,54 @@ Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs. +## Group `registry.client` (attribute_group) + +### Brief + +These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +prefix: client + +### Attributes + + +#### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + ## Group `registry.db` (attribute_group) ### Brief @@ -525,253 +662,548 @@ An identifier (address, unique name, or any other identifier) of the database in -## Group `registry.http` (attribute_group) +## Group `registry.gen_ai` (attribute_group) ### Brief -This document defines semantic convention attributes in the HTTP namespace. +This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. -prefix: http +prefix: gen_ai ### Attributes -#### Attribute `http.request.body.size` +#### Attribute `gen_ai.system` -The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - Requirement Level: Recommended -- Type: int -- Examples: 3495 +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai - Stability: Experimental -#### Attribute `http.request.header` - -HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. - +#### Attribute `gen_ai.request.model` +The name of the GenAI model a request is being made to. -Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. -The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - Requirement Level: Recommended -- Type: template[string[]] -- Examples: [ - "http.request.header.content-type=[\"application/json\"]", - "http.request.header.x-forwarded-for=[\"1.2.3.4\", \"1.2.3.5\"]", -] +- Type: string +- Examples: gpt-4 -- Stability: Stable +- Stability: Experimental -#### Attribute `http.request.method` - -HTTP request method. - - -HTTP request method value SHOULD be "known" to the instrumentation. -By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +#### Attribute `gen_ai.request.max_tokens` -If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override -the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named -OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods -(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). +The maximum number of tokens the model generates for a request. -HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. -Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. -Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. - Requirement Level: Recommended -- Type: Enum [CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE, _OTHER] +- Type: int - Examples: [ - "GET", - "POST", - "HEAD", + 100, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.request.method_original` +#### Attribute `gen_ai.request.temperature` -Original HTTP method sent by the client in the request line. +The temperature setting for the GenAI request. - Requirement Level: Recommended -- Type: string +- Type: double - Examples: [ - "GeT", - "ACL", - "foo", + 0.0, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.request.resend_count` - -The ordinal number of request resending attempt (for any reason, including redirects). - +#### Attribute `gen_ai.request.top_p` +The top_p sampling setting for the GenAI request. -The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). - Requirement Level: Recommended -- Type: int -- Examples: 3 +- Tag: llm-generic-request -- Stability: Stable +- Type: double +- Examples: [ + 1.0, +] +- Stability: Experimental -#### Attribute `http.response.body.size` - -The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. + +#### Attribute `gen_ai.request.top_k` +The top_k sampling setting for the GenAI request. - Requirement Level: Recommended -- Type: int -- Examples: 3495 +- Type: double +- Examples: [ + 1.0, +] - Stability: Experimental -#### Attribute `http.response.header` - -HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. +#### Attribute `gen_ai.request.stop_sequences` +List of sequences that the model will use to stop generating further tokens. -Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -Users MAY explicitly configure instrumentations to capture them even though it is not recommended. -The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - - Requirement Level: Recommended -- Type: template[string[]] +- Type: string[] - Examples: [ - "http.response.header.content-type=[\"application/json\"]", - "http.response.header.my-custom-header=[\"abc\", \"def\"]", + "forest", + "lived", ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.response.status_code` +#### Attribute `gen_ai.request.frequency_penalty` -[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). +The frequency penalty setting for the GenAI request. - Requirement Level: Recommended -- Type: int +- Type: double - Examples: [ - 200, + 0.1, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.route` - -The matched route, that is, the path template in the format used by the respective server framework. - +#### Attribute `gen_ai.request.presence_penalty` +The presence penalty setting for the GenAI request. -MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - Requirement Level: Recommended -- Type: string +- Type: double - Examples: [ - "/users/:userID?", - "{controller}/{action}/{id?}", + 0.1, ] -- Stability: Stable - +- Stability: Experimental -## Group `registry.network` (attribute_group) - -### Brief - -These attributes may be used for any network related operation. - -prefix: network +#### Attribute `gen_ai.response.id` -### Attributes - - -#### Attribute `network.carrier.icc` - -The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. +The unique identifier for the completion. - Requirement Level: Recommended - Type: string -- Examples: DE +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental -#### Attribute `network.carrier.mcc` +#### Attribute `gen_ai.response.model` -The mobile carrier country code. +The name of the model that generated the response. - Requirement Level: Recommended - Type: string -- Examples: 310 +- Examples: [ + "gpt-4-0613", +] +- Stability: Experimental -#### Attribute `network.carrier.mnc` + +#### Attribute `gen_ai.response.finish_reasons` -The mobile carrier network code. +Array of reasons the model stopped generating tokens, corresponding to each generation received. - Requirement Level: Recommended -- Type: string -- Examples: 001 +- Type: string[] +- Examples: [ + "stop", +] +- Stability: Experimental -#### Attribute `network.carrier.name` + +#### Attribute `gen_ai.usage.input_tokens` -The name of the mobile carrier. +The number of tokens used in the GenAI input (prompt). - Requirement Level: Recommended -- Type: string -- Examples: sprint +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental -#### Attribute `network.connection.subtype` +#### Attribute `gen_ai.usage.output_tokens` -This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. +The number of tokens used in the GenAI response (completion). - Requirement Level: Recommended -- Type: Enum [gprs, edge, umts, cdma, evdo_0, evdo_a, cdma2000_1xrtt, hsdpa, hsupa, hspa, iden, evdo_b, lte, ehrpd, hspap, gsm, td_scdma, iwlan, nr, nrnsa, lte_ca] -- Examples: LTE - +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.token.type` + +The type of token being counted. + + +- Requirement Level: Recommended + +- Type: Enum [input, output] +- Examples: [ + "input", + "output", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.completion` + +The full response received from the GenAI model. + + +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Recommended + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + + +## Group `registry.http` (attribute_group) + +### Brief + +This document defines semantic convention attributes in the HTTP namespace. + +prefix: http + +### Attributes + + +#### Attribute `http.request.body.size` + +The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. + + + +- Requirement Level: Recommended + +- Type: int +- Examples: 3495 + +- Stability: Experimental + + +#### Attribute `http.request.header` + +HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. + + + +Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "http.request.header.content-type=[\"application/json\"]", + "http.request.header.x-forwarded-for=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Stable + + +#### Attribute `http.request.method` + +HTTP request method. + + +HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +- Requirement Level: Recommended + +- Type: Enum [CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE, _OTHER] +- Examples: [ + "GET", + "POST", + "HEAD", +] + +- Stability: Stable + + +#### Attribute `http.request.method_original` + +Original HTTP method sent by the client in the request line. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "GeT", + "ACL", + "foo", +] + +- Stability: Stable + + +#### Attribute `http.request.resend_count` + +The ordinal number of request resending attempt (for any reason, including redirects). + + + +The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). + +- Requirement Level: Recommended + +- Type: int +- Examples: 3 + +- Stability: Stable + + +#### Attribute `http.response.body.size` + +The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. + + + +- Requirement Level: Recommended + +- Type: int +- Examples: 3495 + +- Stability: Experimental + + +#### Attribute `http.response.header` + +HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. + + + +Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "http.response.header.content-type=[\"application/json\"]", + "http.response.header.my-custom-header=[\"abc\", \"def\"]", +] + +- Stability: Stable + + +#### Attribute `http.response.status_code` + +[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 200, +] + +- Stability: Stable + + +#### Attribute `http.route` + +The matched route, that is, the path template in the format used by the respective server framework. + + + +MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "/users/:userID?", + "{controller}/{action}/{id?}", +] + +- Stability: Stable + + + +## Group `registry.network` (attribute_group) + +### Brief + +These attributes may be used for any network related operation. + +prefix: network + +### Attributes + + +#### Attribute `network.carrier.icc` + +The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. + + +- Requirement Level: Recommended + +- Type: string +- Examples: DE + + +#### Attribute `network.carrier.mcc` + +The mobile carrier country code. + + +- Requirement Level: Recommended + +- Type: string +- Examples: 310 + + +#### Attribute `network.carrier.mnc` + +The mobile carrier network code. + + +- Requirement Level: Recommended + +- Type: string +- Examples: 001 + + +#### Attribute `network.carrier.name` + +The name of the mobile carrier. + + +- Requirement Level: Recommended + +- Type: string +- Examples: sprint + + +#### Attribute `network.connection.subtype` + +This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. + + +- Requirement Level: Recommended + +- Type: Enum [gprs, edge, umts, cdma, evdo_0, evdo_a, cdma2000_1xrtt, hsdpa, hsupa, hspa, iden, evdo_b, lte, ehrpd, hspap, gsm, td_scdma, iwlan, nr, nrnsa, lte_ca] +- Examples: LTE + #### Attribute `network.connection.type` @@ -935,6 +1367,272 @@ The network IO operation direction. +## Group `registry.rpc` (attribute_group) + +### Brief + +This document defines attributes for remote procedure calls. + +prefix: rpc + +### Attributes + + +#### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Recommended + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Recommended + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Recommended + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +#### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + + ## Group `server` (attribute_group) ### Brief diff --git a/crates/weaver_forge/expected_output/test/event/android_lifecycle_events.md b/crates/weaver_forge/expected_output/test/event/android_lifecycle_events.md deleted file mode 100644 index de690580..00000000 --- a/crates/weaver_forge/expected_output/test/event/android_lifecycle_events.md +++ /dev/null @@ -1,27 +0,0 @@ -# Group `android.lifecycle.events` (event) - -## Brief - -This event represents an occurrence of a lifecycle transition on the Android platform. - -Prefix: android -Name: device.app.lifecycle - -## Attributes - - -### Attribute `android.state` - -This attribute represents the state the application has transitioned into at the occurrence of the event. - - - -The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. - -- Requirement Level: Required - -- Type: Enum [created, background, foreground] - -- Stability: Experimental - - \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/event/device_app_lifecycle.md b/crates/weaver_forge/expected_output/test/event/device_app_lifecycle.md new file mode 100644 index 00000000..8c5521a8 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/event/device_app_lifecycle.md @@ -0,0 +1,33 @@ +# Group `device.app.lifecycle` (event) + +## Brief + +This event represents an occurrence of a lifecycle transition on Android or iOS platform. + +Prefix: +Name: device.app.lifecycle + +### Body Fields + +#### Field `ios.state` + +This attribute represents the state the application has transitioned into at the occurrence of the event. + +The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. + +- Requirement Level: Conditionally Required - if and only if `os.name` is `ios` +- Type: Enum [active, inactive, background, foreground, terminate] +- Stability: Experimental + +#### Field `android.state` + +This attribute represents the state the application has transitioned into at the occurrence of the event. + +The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +- Requirement Level: Conditionally Required - if and only if `os.name` is `android` +- Type: Enum [created, background, foreground] +- Stability: Experimental + +## Attributes + diff --git a/crates/weaver_forge/expected_output/test/event/feature_flag.md b/crates/weaver_forge/expected_output/test/event/feature_flag.md new file mode 100644 index 00000000..a93f8cb5 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/event/feature_flag.md @@ -0,0 +1,65 @@ +# Group `feature_flag` (event) + +## Brief + +This semantic convention defines the attributes used to represent a feature flag evaluation as an event. + +Prefix: feature_flag +Name: none + +### Body Fields + +No event body defined.## Attributes + + +### Attribute `feature_flag.key` + +The unique identifier of the feature flag. + + +- Requirement Level: Required + +- Type: string +- Examples: [ + "logo-color", +] + + +### Attribute `feature_flag.provider_name` + +The name of the service provider that performs the flag evaluation. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Flag Manager", +] + + +### Attribute `feature_flag.variant` + +SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. + + + +A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +A stringified version of the value can be used in situations where a +semantic identifier is unavailable. String representation of the value +should be determined by the implementer. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "red", + "true", + "on", +] + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/event/gen_ai_content_completion.md b/crates/weaver_forge/expected_output/test/event/gen_ai_content_completion.md new file mode 100644 index 00000000..74c1acec --- /dev/null +++ b/crates/weaver_forge/expected_output/test/event/gen_ai_content_completion.md @@ -0,0 +1,31 @@ +# Group `gen_ai.content.completion` (event) + +## Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +Prefix: +Name: gen_ai.content.completion + +### Body Fields + +No event body defined.## Attributes + + +### Attribute `gen_ai.completion` + +The full response received from the GenAI model. + + +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/event/gen_ai_content_prompt.md b/crates/weaver_forge/expected_output/test/event/gen_ai_content_prompt.md new file mode 100644 index 00000000..cb1add47 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/event/gen_ai_content_prompt.md @@ -0,0 +1,31 @@ +# Group `gen_ai.content.prompt` (event) + +## Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +Prefix: +Name: gen_ai.content.prompt + +### Body Fields + +No event body defined.## Attributes + + +### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/event/ios_lifecycle_events.md b/crates/weaver_forge/expected_output/test/event/ios_lifecycle_events.md deleted file mode 100644 index 83ecf5db..00000000 --- a/crates/weaver_forge/expected_output/test/event/ios_lifecycle_events.md +++ /dev/null @@ -1,27 +0,0 @@ -# Group `ios.lifecycle.events` (event) - -## Brief - -This event represents an occurrence of a lifecycle transition on the iOS platform. - -Prefix: ios -Name: device.app.lifecycle - -## Attributes - - -### Attribute `ios.state` - -This attribute represents the state the application has transitioned into at the occurrence of the event. - - - -The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. - -- Requirement Level: Required - -- Type: Enum [active, inactive, background, foreground, terminate] - -- Stability: Experimental - - \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/event/rpc_message.md b/crates/weaver_forge/expected_output/test/event/rpc_message.md new file mode 100644 index 00000000..335c3f6f --- /dev/null +++ b/crates/weaver_forge/expected_output/test/event/rpc_message.md @@ -0,0 +1,64 @@ +# Group `rpc.message` (event) + +## Brief + +RPC received/sent message. + +Prefix: rpc.message +Name: none + +### Body Fields + +No event body defined.## Attributes + + +### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/event/trace_exception.md b/crates/weaver_forge/expected_output/test/event/trace_exception.md new file mode 100644 index 00000000..0c9970e6 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/event/trace_exception.md @@ -0,0 +1,91 @@ +# Group `trace-exception` (event) + +## Brief + +This document defines the attributes used to report a single exception associated with a span. + +Prefix: exception +Name: none + +### Body Fields + +No event body defined.## Attributes + + +### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + +### Attribute `exception.type` + +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. + + + +- Requirement Level: Conditionally Required - Required if `exception.message` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Conditionally Required - Required if `exception.type` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/events.md b/crates/weaver_forge/expected_output/test/events.md index 8066e504..2a5653d6 100644 --- a/crates/weaver_forge/expected_output/test/events.md +++ b/crates/weaver_forge/expected_output/test/events.md @@ -1,57 +1,333 @@ # Semantic Convention Event Groups -## Group `ios.lifecycle.events` (event) +## Group `device.app.lifecycle` (event) ### Brief -This event represents an occurrence of a lifecycle transition on the iOS platform. +This event represents an occurrence of a lifecycle transition on Android or iOS platform. -Prefix: ios +Prefix: Name: device.app.lifecycle -### Attributes +### Body Fields + +#### Field `ios.state` + +This attribute represents the state the application has transitioned into at the occurrence of the event. + +The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. +- Requirement Level: Conditionally Required - if and only if `os.name` is `ios` +- Type: Enum [active, inactive, background, foreground, terminate] +- Stability: Experimental -#### Attribute `ios.state` +#### Field `android.state` This attribute represents the state the application has transitioned into at the occurrence of the event. +The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +- Requirement Level: Conditionally Required - if and only if `os.name` is `android` +- Type: Enum [created, background, foreground] +- Stability: Experimental +### Attributes + + + +## Group `trace-exception` (event) + +### Brief + +This document defines the attributes used to report a single exception associated with a span. + +Prefix: exception +Name: none + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +#### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + +#### Attribute `exception.type` + +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. + + + +- Requirement Level: Conditionally Required - Required if `exception.message` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +#### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Conditionally Required - Required if `exception.type` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + + +## Group `feature_flag` (event) + +### Brief + +This semantic convention defines the attributes used to represent a feature flag evaluation as an event. + +Prefix: feature_flag +Name: none + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `feature_flag.key` + +The unique identifier of the feature flag. -The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. - Requirement Level: Required -- Type: Enum [active, inactive, background, foreground, terminate] +- Type: string +- Examples: [ + "logo-color", +] + + +#### Attribute `feature_flag.provider_name` + +The name of the service provider that performs the flag evaluation. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Flag Manager", +] + + +#### Attribute `feature_flag.variant` + +SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. + + + +A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +A stringified version of the value can be used in situations where a +semantic identifier is unavailable. String representation of the value +should be determined by the implementer. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "red", + "true", + "on", +] + + + +## Group `gen_ai.content.prompt` (event) + +### Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +Prefix: +Name: gen_ai.content.prompt + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] - Stability: Experimental -## Group `android.lifecycle.events` (event) +## Group `gen_ai.content.completion` (event) ### Brief -This event represents an occurrence of a lifecycle transition on the Android platform. +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. -Prefix: android -Name: device.app.lifecycle +Prefix: +Name: gen_ai.content.completion + +### Body Fields + +No event body defined. ### Attributes -#### Attribute `android.state` +#### Attribute `gen_ai.completion` -This attribute represents the state the application has transitioned into at the occurrence of the event. +The full response received from the GenAI model. +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) -The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + + +## Group `rpc.message` (event) -- Requirement Level: Required +### Brief + +RPC received/sent message. + +Prefix: rpc.message +Name: none + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended -- Type: Enum [created, background, foreground] +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +#### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int - Stability: Experimental diff --git a/crates/weaver_forge/expected_output/test/group/android_lifecycle_events.md b/crates/weaver_forge/expected_output/test/group/android_lifecycle_events.md deleted file mode 100644 index 1eba53e2..00000000 --- a/crates/weaver_forge/expected_output/test/group/android_lifecycle_events.md +++ /dev/null @@ -1,31 +0,0 @@ -# Group `android.lifecycle.events` (event) - -## Brief - -This event represents an occurrence of a lifecycle transition on the Android platform. - -prefix: android - -## Attributes - - -### Attribute `android.state` - -This attribute represents the state the application has transitioned into at the occurrence of the event. - - - -The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. - -- Requirement Level: Required - -- Type: Enum [created, background, foreground] - -- Stability: Experimental - - - -## Lineage - -Source file: data/mobile-events.yaml - diff --git a/crates/weaver_forge/expected_output/test/group/device_app_lifecycle.md b/crates/weaver_forge/expected_output/test/group/device_app_lifecycle.md new file mode 100644 index 00000000..1db22557 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/device_app_lifecycle.md @@ -0,0 +1,38 @@ +# Group `device.app.lifecycle` (event) + +## Brief + +This event represents an occurrence of a lifecycle transition on Android or iOS platform. + +prefix: + +### Body Fields + +#### Field `ios.state` + +This attribute represents the state the application has transitioned into at the occurrence of the event. + +The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. + +- Requirement Level: Conditionally Required - if and only if `os.name` is `ios` +- Type: Enum [active, inactive, background, foreground, terminate] +- Stability: Experimental + +#### Field `android.state` + +This attribute represents the state the application has transitioned into at the occurrence of the event. + +The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +- Requirement Level: Conditionally Required - if and only if `os.name` is `android` +- Type: Enum [created, background, foreground] +- Stability: Experimental + +## Attributes + + + +## Lineage + +Source file: data/mobile-events.yaml + diff --git a/crates/weaver_forge/expected_output/test/group/feature_flag.md b/crates/weaver_forge/expected_output/test/group/feature_flag.md new file mode 100644 index 00000000..5ac6a602 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/feature_flag.md @@ -0,0 +1,71 @@ +# Group `feature_flag` (event) + +## Brief + +This semantic convention defines the attributes used to represent a feature flag evaluation as an event. + +prefix: feature_flag + +### Body Fields + +No event body defined. + +## Attributes + + +### Attribute `feature_flag.key` + +The unique identifier of the feature flag. + + +- Requirement Level: Required + +- Type: string +- Examples: [ + "logo-color", +] + + +### Attribute `feature_flag.provider_name` + +The name of the service provider that performs the flag evaluation. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Flag Manager", +] + + +### Attribute `feature_flag.variant` + +SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. + + + +A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +A stringified version of the value can be used in situations where a +semantic identifier is unavailable. String representation of the value +should be determined by the implementer. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "red", + "true", + "on", +] + + + +## Lineage + +Source file: data/trace-feature-flag.yaml + diff --git a/crates/weaver_forge/expected_output/test/group/gen_ai_content_completion.md b/crates/weaver_forge/expected_output/test/group/gen_ai_content_completion.md new file mode 100644 index 00000000..356170eb --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/gen_ai_content_completion.md @@ -0,0 +1,42 @@ +# Group `gen_ai.content.completion` (event) + +## Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +prefix: + +### Body Fields + +No event body defined. + +## Attributes + + +### Attribute `gen_ai.completion` + +The full response received from the GenAI model. + + +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-gen-ai.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/gen_ai_content_prompt.md b/crates/weaver_forge/expected_output/test/group/gen_ai_content_prompt.md new file mode 100644 index 00000000..4eed0f6c --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/gen_ai_content_prompt.md @@ -0,0 +1,42 @@ +# Group `gen_ai.content.prompt` (event) + +## Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +prefix: + +### Body Fields + +No event body defined. + +## Attributes + + +### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-gen-ai.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/ios_lifecycle_events.md b/crates/weaver_forge/expected_output/test/group/ios_lifecycle_events.md deleted file mode 100644 index b36ffa8d..00000000 --- a/crates/weaver_forge/expected_output/test/group/ios_lifecycle_events.md +++ /dev/null @@ -1,31 +0,0 @@ -# Group `ios.lifecycle.events` (event) - -## Brief - -This event represents an occurrence of a lifecycle transition on the iOS platform. - -prefix: ios - -## Attributes - - -### Attribute `ios.state` - -This attribute represents the state the application has transitioned into at the occurrence of the event. - - - -The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. - -- Requirement Level: Required - -- Type: Enum [active, inactive, background, foreground, terminate] - -- Stability: Experimental - - - -## Lineage - -Source file: data/mobile-events.yaml - diff --git a/crates/weaver_forge/expected_output/test/group/registry_client.md b/crates/weaver_forge/expected_output/test/group/registry_client.md new file mode 100644 index 00000000..28298806 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/registry_client.md @@ -0,0 +1,52 @@ +# Group `registry.client` (attribute_group) + +## Brief + +These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +prefix: client + +## Attributes + + +### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Lineage + +Source file: data/registry-client.yaml + diff --git a/crates/weaver_forge/expected_output/test/group/registry_exception.md b/crates/weaver_forge/expected_output/test/group/registry_exception.md new file mode 100644 index 00000000..ffe4fb52 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/registry_exception.md @@ -0,0 +1,93 @@ +# Group `registry.exception` (attribute_group) + +## Brief + +This document defines the shared attributes used to report a single exception associated with a span or log. + +prefix: exception + +## Attributes + + +### Attribute `exception.type` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + +### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + + +## Lineage + +Source file: data/exception.yaml + diff --git a/crates/weaver_forge/expected_output/test/group/registry_gen_ai.md b/crates/weaver_forge/expected_output/test/group/registry_gen_ai.md new file mode 100644 index 00000000..d2187009 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/registry_gen_ai.md @@ -0,0 +1,299 @@ +# Group `registry.gen_ai` (attribute_group) + +## Brief + +This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. + +prefix: gen_ai + +## Attributes + + +### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +- Requirement Level: Recommended + +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai + +- Stability: Experimental + + +### Attribute `gen_ai.request.model` + +The name of the GenAI model a request is being made to. + + +- Requirement Level: Recommended + +- Type: string +- Examples: gpt-4 + +- Stability: Experimental + + +### Attribute `gen_ai.request.max_tokens` + +The maximum number of tokens the model generates for a request. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.temperature` + +The temperature setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.0, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.top_p` + +The top_p sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Tag: llm-generic-request + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.top_k` + +The top_k sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.stop_sequences` + +List of sequences that the model will use to stop generating further tokens. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "forest", + "lived", +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.frequency_penalty` + +The frequency penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.presence_penalty` + +The presence penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +### Attribute `gen_ai.response.id` + +The unique identifier for the completion. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental + + +### Attribute `gen_ai.response.model` + +The name of the model that generated the response. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental + + +### Attribute `gen_ai.response.finish_reasons` + +Array of reasons the model stopped generating tokens, corresponding to each generation received. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental + + +### Attribute `gen_ai.usage.input_tokens` + +The number of tokens used in the GenAI input (prompt). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +### Attribute `gen_ai.usage.output_tokens` + +The number of tokens used in the GenAI response (completion). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +### Attribute `gen_ai.token.type` + +The type of token being counted. + + +- Requirement Level: Recommended + +- Type: Enum [input, output] +- Examples: [ + "input", + "output", +] + +- Stability: Experimental + + +### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] + +- Stability: Experimental + + +### Attribute `gen_ai.completion` + +The full response received from the GenAI model. + + +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + +### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Recommended + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + + +## Lineage + +Source file: data/registry-gen_ai.yaml + diff --git a/crates/weaver_forge/expected_output/test/group/registry_rpc.md b/crates/weaver_forge/expected_output/test/group/registry_rpc.md new file mode 100644 index 00000000..b6f160b1 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/registry_rpc.md @@ -0,0 +1,270 @@ +# Group `registry.rpc` (attribute_group) + +## Brief + +This document defines attributes for remote procedure calls. + +prefix: rpc + +## Attributes + + +### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Recommended + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Recommended + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + +### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Recommended + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Recommended + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + + +## Lineage + +Source file: data/registry-rpc.yaml + diff --git a/crates/weaver_forge/expected_output/test/group/rpc.md b/crates/weaver_forge/expected_output/test/group/rpc.md new file mode 100644 index 00000000..797a0624 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc.md @@ -0,0 +1,173 @@ +# Group `rpc` (span) + +## Brief + +This document defines semantic conventions for remote procedure calls. + +prefix: rpc + +## Attributes + + +### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/rpc_client.md b/crates/weaver_forge/expected_output/test/group/rpc_client.md new file mode 100644 index 00000000..58e94762 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc_client.md @@ -0,0 +1,214 @@ +# Group `rpc.client` (span) + +## Brief + +This document defines semantic conventions for remote procedure call client spans. + +prefix: + +## Attributes + + +### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/rpc_connect_rpc.md b/crates/weaver_forge/expected_output/test/group/rpc_connect_rpc.md new file mode 100644 index 00000000..47d6a4ad --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc_connect_rpc.md @@ -0,0 +1,242 @@ +# Group `rpc.connect_rpc` (span) + +## Brief + +Tech-specific attributes for Connect RPC. + +prefix: + +## Attributes + + +### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Conditionally Required - If response is not successful and if error code available. + +- Tag: connect_rpc-tech-specific + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/rpc_grpc.md b/crates/weaver_forge/expected_output/test/group/rpc_grpc.md new file mode 100644 index 00000000..2759c5ff --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc_grpc.md @@ -0,0 +1,242 @@ +# Group `rpc.grpc` (span) + +## Brief + +Tech-specific attributes for gRPC. + +prefix: + +## Attributes + + +### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Required + +- Tag: grpc-tech-specific + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/rpc_jsonrpc.md b/crates/weaver_forge/expected_output/test/group/rpc_jsonrpc.md new file mode 100644 index 00000000..609e5d7e --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc_jsonrpc.md @@ -0,0 +1,269 @@ +# Group `rpc.jsonrpc` (span) + +## Brief + +Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/). + +prefix: rpc.jsonrpc + +## Attributes + + +### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Conditionally Required - If response is not successful. + +- Tag: jsonrpc-tech-specific + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Conditionally Required - If other than the default version (`1.0`) + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is always required for jsonrpc. See the note in the general RPC conventions for more information. + +- Requirement Level: Required + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/rpc_message.md b/crates/weaver_forge/expected_output/test/group/rpc_message.md new file mode 100644 index 00000000..6ec972d9 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc_message.md @@ -0,0 +1,90 @@ +# Group `rpc.message` (event) + +## Brief + +RPC received/sent message. + +prefix: rpc.message + +### Body Fields + +No event body defined. + +## Attributes + + +### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/rpc_server.md b/crates/weaver_forge/expected_output/test/group/rpc_server.md new file mode 100644 index 00000000..98a8c195 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/rpc_server.md @@ -0,0 +1,260 @@ +# Group `rpc.server` (span) + +## Brief + +Semantic Convention for RPC server spans + +prefix: + +## Attributes + + +### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + +### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Lineage + +Source file: data/trace-rpc.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/trace_exception.md b/crates/weaver_forge/expected_output/test/group/trace_exception.md new file mode 100644 index 00000000..9c66a6ec --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/trace_exception.md @@ -0,0 +1,117 @@ +# Group `trace-exception` (event) + +## Brief + +This document defines the attributes used to report a single exception associated with a span. + +prefix: exception + +### Body Fields + +No event body defined. + +## Attributes + + +### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + +### Attribute `exception.type` + +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. + + + +- Requirement Level: Conditionally Required - Required if `exception.message` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Conditionally Required - Required if `exception.type` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + + +## Lineage + +Source file: data/trace-exception.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/group/trace_gen_ai_client.md b/crates/weaver_forge/expected_output/test/group/trace_gen_ai_client.md new file mode 100644 index 00000000..818a2dab --- /dev/null +++ b/crates/weaver_forge/expected_output/test/group/trace_gen_ai_client.md @@ -0,0 +1,328 @@ +# Group `trace.gen_ai.client` (span) + +## Brief + +Describes GenAI operation span. + +prefix: + +## Attributes + + +### Attribute `gen_ai.request.max_tokens` + +The maximum number of tokens the model generates for a request. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.temperature` + +The temperature setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.0, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.top_p` + +The top_p sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Tag: llm-generic-request + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.top_k` + +The top_k sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.stop_sequences` + +List of sequences that the model will use to stop generating further tokens. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "forest", + "lived", +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.frequency_penalty` + +The frequency penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +### Attribute `gen_ai.request.presence_penalty` + +The presence penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +### Attribute `gen_ai.response.id` + +The unique identifier for the completion. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental + + +### Attribute `gen_ai.response.finish_reasons` + +Array of reasons the model stopped generating tokens, corresponding to each generation received. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental + + +### Attribute `gen_ai.usage.input_tokens` + +The number of tokens used in the GenAI input (prompt). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +### Attribute `gen_ai.usage.output_tokens` + +The number of tokens used in the GenAI response (completion). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +- Requirement Level: Required + +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai + +- Stability: Experimental + + +### Attribute `gen_ai.request.model` + +The name of the GenAI model a request is being made to. + + +The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Required + +- Type: string +- Examples: gpt-4 + +- Stability: Experimental + + +### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Required + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + +### Attribute `gen_ai.response.model` + +The name of the model that generated the response. + + +If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental + + + +## Lineage + +Source file: data/trace-gen-ai.yaml + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + +attribute: + - source group: + - inherited fields: + - locally overridden fields: + diff --git a/crates/weaver_forge/expected_output/test/groups.md b/crates/weaver_forge/expected_output/test/groups.md index bb89d4df..93a66fde 100644 --- a/crates/weaver_forge/expected_output/test/groups.md +++ b/crates/weaver_forge/expected_output/test/groups.md @@ -1,6 +1,95 @@ # Semantic Convention Groups +## Group `registry.exception` (attribute_group) + +### Brief + +This document defines the shared attributes used to report a single exception associated with a span or log. + +prefix: exception + +### Attributes + + +#### Attribute `exception.type` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +#### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + +#### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +#### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + + ## Group `otel.scope` (resource) ### Brief @@ -478,57 +567,85 @@ prefix: -## Group `ios.lifecycle.events` (event) +## Group `device.app.lifecycle` (event) ### Brief -This event represents an occurrence of a lifecycle transition on the iOS platform. - -prefix: ios +This event represents an occurrence of a lifecycle transition on Android or iOS platform. -### Attributes +prefix: +### Body Fields -#### Attribute `ios.state` +#### Field `ios.state` This attribute represents the state the application has transitioned into at the occurrence of the event. - - The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. -- Requirement Level: Required - +- Requirement Level: Conditionally Required - if and only if `os.name` is `ios` - Type: Enum [active, inactive, background, foreground, terminate] - - Stability: Experimental - - -## Group `android.lifecycle.events` (event) +#### Field `android.state` + +This attribute represents the state the application has transitioned into at the occurrence of the event. + +The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +- Requirement Level: Conditionally Required - if and only if `os.name` is `android` +- Type: Enum [created, background, foreground] +- Stability: Experimental + +### Attributes + + + +## Group `registry.client` (attribute_group) ### Brief -This event represents an occurrence of a lifecycle transition on the Android platform. +These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. -prefix: android +prefix: client ### Attributes -#### Attribute `android.state` +#### Attribute `client.address` -This attribute represents the state the application has transitioned into at the occurrence of the event. +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +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. -The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `client.port` -- Requirement Level: Required +Client port number. + + +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. + +- Requirement Level: Recommended -- Type: Enum [created, background, foreground] +- Type: int +- Examples: [ + 65123, +] -- Stability: Experimental +- Stability: Stable @@ -1006,733 +1123,600 @@ An identifier (address, unique name, or any other identifier) of the database in -## Group `registry.http` (attribute_group) +## Group `registry.gen_ai` (attribute_group) ### Brief -This document defines semantic convention attributes in the HTTP namespace. +This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. -prefix: http +prefix: gen_ai ### Attributes -#### Attribute `http.request.body.size` +#### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. -The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - Requirement Level: Recommended -- Type: int -- Examples: 3495 +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai - Stability: Experimental -#### Attribute `http.request.header` - -HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. +#### Attribute `gen_ai.request.model` +The name of the GenAI model a request is being made to. -Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. -The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - - Requirement Level: Recommended -- Type: template[string[]] -- Examples: [ - "http.request.header.content-type=[\"application/json\"]", - "http.request.header.x-forwarded-for=[\"1.2.3.4\", \"1.2.3.5\"]", -] +- Type: string +- Examples: gpt-4 -- Stability: Stable +- Stability: Experimental -#### Attribute `http.request.method` - -HTTP request method. - - -HTTP request method value SHOULD be "known" to the instrumentation. -By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +#### Attribute `gen_ai.request.max_tokens` -If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override -the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named -OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods -(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). +The maximum number of tokens the model generates for a request. -HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. -Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. -Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. - Requirement Level: Recommended -- Type: Enum [CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE, _OTHER] +- Type: int - Examples: [ - "GET", - "POST", - "HEAD", + 100, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.request.method_original` +#### Attribute `gen_ai.request.temperature` -Original HTTP method sent by the client in the request line. +The temperature setting for the GenAI request. - Requirement Level: Recommended -- Type: string +- Type: double - Examples: [ - "GeT", - "ACL", - "foo", + 0.0, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.request.resend_count` - -The ordinal number of request resending attempt (for any reason, including redirects). +#### Attribute `gen_ai.request.top_p` +The top_p sampling setting for the GenAI request. -The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). - - Requirement Level: Recommended -- Type: int -- Examples: 3 +- Tag: llm-generic-request -- Stability: Stable +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental -#### Attribute `http.response.body.size` - -The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. +#### Attribute `gen_ai.request.top_k` +The top_k sampling setting for the GenAI request. - Requirement Level: Recommended -- Type: int -- Examples: 3495 +- Type: double +- Examples: [ + 1.0, +] - Stability: Experimental -#### Attribute `http.response.header` - -HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. - +#### Attribute `gen_ai.request.stop_sequences` +List of sequences that the model will use to stop generating further tokens. -Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -Users MAY explicitly configure instrumentations to capture them even though it is not recommended. -The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - Requirement Level: Recommended -- Type: template[string[]] +- Type: string[] - Examples: [ - "http.response.header.content-type=[\"application/json\"]", - "http.response.header.my-custom-header=[\"abc\", \"def\"]", + "forest", + "lived", ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.response.status_code` +#### Attribute `gen_ai.request.frequency_penalty` -[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). +The frequency penalty setting for the GenAI request. - Requirement Level: Recommended -- Type: int +- Type: double - Examples: [ - 200, + 0.1, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `http.route` - -The matched route, that is, the path template in the format used by the respective server framework. +#### Attribute `gen_ai.request.presence_penalty` +The presence penalty setting for the GenAI request. -MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - - Requirement Level: Recommended -- Type: string +- Type: double - Examples: [ - "/users/:userID?", - "{controller}/{action}/{id?}", + 0.1, ] -- Stability: Stable +- Stability: Experimental +#### Attribute `gen_ai.response.id` -## Group `registry.network` (attribute_group) - -### Brief - -These attributes may be used for any network related operation. - -prefix: network - -### Attributes - - -#### Attribute `network.carrier.icc` - -The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. +The unique identifier for the completion. - Requirement Level: Recommended - Type: string -- Examples: DE +- Examples: [ + "chatcmpl-123", +] +- Stability: Experimental -#### Attribute `network.carrier.mcc` + +#### Attribute `gen_ai.response.model` -The mobile carrier country code. +The name of the model that generated the response. - Requirement Level: Recommended - Type: string -- Examples: 310 +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental -#### Attribute `network.carrier.mnc` +#### Attribute `gen_ai.response.finish_reasons` -The mobile carrier network code. +Array of reasons the model stopped generating tokens, corresponding to each generation received. - Requirement Level: Recommended -- Type: string -- Examples: 001 +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental -#### Attribute `network.carrier.name` +#### Attribute `gen_ai.usage.input_tokens` -The name of the mobile carrier. +The number of tokens used in the GenAI input (prompt). - Requirement Level: Recommended -- Type: string -- Examples: sprint - - -#### Attribute `network.connection.subtype` - -This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. - - -- Requirement Level: Recommended - -- Type: Enum [gprs, edge, umts, cdma, evdo_0, evdo_a, cdma2000_1xrtt, hsdpa, hsupa, hspa, iden, evdo_b, lte, ehrpd, hspap, gsm, td_scdma, iwlan, nr, nrnsa, lte_ca] -- Examples: LTE - - -#### Attribute `network.connection.type` - -The internet connection type. - - -- Requirement Level: Recommended - -- Type: Enum [wifi, wired, cell, unavailable, unknown] -- Examples: wifi - - -#### Attribute `network.local.address` - -Local address of the network connection - IP address or Unix domain socket name. - - -- Requirement Level: Recommended - -- Type: string +- Type: int - Examples: [ - "10.1.2.80", - "/tmp/my.sock", + 100, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `network.local.port` +#### Attribute `gen_ai.usage.output_tokens` -Local port number of the network connection. +The number of tokens used in the GenAI response (completion). - Requirement Level: Recommended - Type: int - Examples: [ - 65123, + 180, ] -- Stability: Stable +- Stability: Experimental -#### Attribute `network.peer.address` +#### Attribute `gen_ai.token.type` -Peer address of the network connection - IP address or Unix domain socket name. +The type of token being counted. - Requirement Level: Recommended -- Type: string +- Type: Enum [input, output] - Examples: [ - "10.1.2.80", - "/tmp/my.sock", + "input", + "output", ] -- Stability: Stable +- Stability: Experimental -#### Attribute `network.peer.port` +#### Attribute `gen_ai.prompt` -Peer port number of the network connection. +The full prompt sent to the GenAI model. +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + - Requirement Level: Recommended -- Type: int +- Type: string - Examples: [ - 65123, + "[{'role': 'user', 'content': 'What is the capital of France?'}]", ] -- Stability: Stable +- Stability: Experimental -#### Attribute `network.protocol.name` +#### Attribute `gen_ai.completion` -[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. +The full response received from the GenAI model. -The value SHOULD be normalized to lowercase. +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) - Requirement Level: Recommended - Type: string - Examples: [ - "amqp", - "http", - "mqtt", + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", ] -- Stability: Stable +- Stability: Experimental -#### Attribute `network.protocol.version` +#### Attribute `gen_ai.operation.name` -Version of the protocol specified in `network.protocol.name`. +The name of the operation being performed. -`network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +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. - Requirement Level: Recommended -- Type: string -- Examples: 3.1.1 +- Type: Enum [chat, text_completion] -- Stability: Stable +- Stability: Experimental -#### Attribute `network.transport` -[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). +## Group `registry.http` (attribute_group) +### Brief +This document defines semantic convention attributes in the HTTP namespace. -The value SHOULD be normalized to lowercase. +prefix: http -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. +### Attributes -- Requirement Level: Recommended - -- Type: Enum [tcp, udp, pipe, unix] -- Examples: [ - "tcp", - "udp", -] - -- Stability: Stable - - -#### Attribute `network.type` -[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. +#### Attribute `http.request.body.size` + +The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. -The value SHOULD be normalized to lowercase. - Requirement Level: Recommended -- Type: Enum [ipv4, ipv6] -- Examples: [ - "ipv4", - "ipv6", -] +- Type: int +- Examples: 3495 -- Stability: Stable +- Stability: Experimental -#### Attribute `network.io.direction` +#### Attribute `http.request.header` -The network IO operation direction. +HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. + +Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + - Requirement Level: Recommended -- Type: Enum [transmit, receive] +- Type: template[string[]] - Examples: [ - "transmit", + "http.request.header.content-type=[\"application/json\"]", + "http.request.header.x-forwarded-for=[\"1.2.3.4\", \"1.2.3.5\"]", ] +- Stability: Stable + +#### Attribute `http.request.method` -## Group `server` (attribute_group) - -### Brief - -These attributes may be used to describe the server in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. - -prefix: server - -### Attributes +HTTP request method. -#### Attribute `server.address` +HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -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. +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. - Requirement Level: Recommended -- Type: string +- Type: Enum [CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE, _OTHER] - Examples: [ - "example.com", - "10.1.2.80", - "/tmp/my.sock", + "GET", + "POST", + "HEAD", ] - Stability: Stable -#### Attribute `server.port` - -Server port number. +#### Attribute `http.request.method_original` +Original HTTP method sent by the client in the request line. -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. - Requirement Level: Recommended -- Type: int +- Type: string - Examples: [ - 80, - 8080, - 443, + "GeT", + "ACL", + "foo", ] - Stability: Stable +#### Attribute `http.request.resend_count` -## Group `registry.url` (attribute_group) - -### Brief - -Attributes describing URL. - -prefix: url - -### Attributes - +The ordinal number of request resending attempt (for any reason, including redirects). -#### Attribute `url.scheme` -The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. +The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). - Requirement Level: Recommended -- Type: string -- Examples: [ - "https", - "ftp", - "telnet", -] +- Type: int +- Examples: 3 - Stability: Stable -#### Attribute `url.full` +#### Attribute `http.response.body.size` -Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) +The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. -For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. - Requirement Level: Recommended -- Type: string -- Examples: [ - "https://www.foo.bar/search?q=OpenTelemetry#SemConv", - "//localhost", -] +- Type: int +- Examples: 3495 -- Stability: Stable +- Stability: Experimental -#### Attribute `url.path` +#### Attribute `http.response.header` + +HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. + -The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component +Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - Requirement Level: Recommended -- Type: string +- Type: template[string[]] - Examples: [ - "/search", + "http.response.header.content-type=[\"application/json\"]", + "http.response.header.my-custom-header=[\"abc\", \"def\"]", ] - Stability: Stable -#### Attribute `url.query` - -The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component +#### Attribute `http.response.status_code` +[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). -Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. - Requirement Level: Recommended -- Type: string +- Type: int - Examples: [ - "q=OpenTelemetry", + 200, ] - Stability: Stable -#### Attribute `url.fragment` +#### Attribute `http.route` + +The matched route, that is, the path template in the format used by the respective server framework. + -The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component +MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - Requirement Level: Recommended - Type: string - Examples: [ - "SemConv", + "/users/:userID?", + "{controller}/{action}/{id?}", ] - Stability: Stable -## Group `registry.user_agent` (attribute_group) +## Group `registry.network` (attribute_group) ### Brief -Describes user-agent attributes. +These attributes may be used for any network related operation. -prefix: user_agent +prefix: network ### Attributes -#### Attribute `user_agent.original` - -Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. +#### Attribute `network.carrier.icc` +The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. - Requirement Level: Recommended - Type: string -- Examples: [ - "CERN-LineMode/2.15 libwww/2.17b3", - "Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1", -] - -- Stability: Stable +- Examples: DE +#### Attribute `network.carrier.mcc` -## Group `db` (span) - -### Brief - -This document defines the attributes used to perform database client calls. - -prefix: - -### Attributes - - -#### Attribute `db.system` - -An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. +The mobile carrier country code. -- Requirement Level: Required - -- Tag: connection-level +- Requirement Level: Recommended -- Type: Enum [other_sql, mssql, mssqlcompact, mysql, oracle, db2, postgresql, redshift, hive, cloudscape, hsqldb, progress, maxdb, hanadb, ingres, firstsql, edb, cache, adabas, firebird, derby, filemaker, informix, instantdb, interbase, mariadb, netezza, pervasive, pointbase, sqlite, sybase, teradata, vertica, h2, coldfusion, cassandra, hbase, mongodb, redis, couchbase, couchdb, cosmosdb, dynamodb, neo4j, geode, elasticsearch, memcached, cockroachdb, opensearch, clickhouse, spanner, trino] +- Type: string +- Examples: 310 -#### Attribute `db.connection_string` - -The connection string used to connect to the database. It is recommended to remove embedded credentials. +#### Attribute `network.carrier.mnc` +The mobile carrier network code. - Requirement Level: Recommended -- Tag: connection-level - - Type: string -- Examples: Server=(localdb)\v11.0;Integrated Security=true; +- Examples: 001 -#### Attribute `db.user` - -Username for accessing the database. +#### Attribute `network.carrier.name` +The name of the mobile carrier. - Requirement Level: Recommended -- Tag: connection-level - - Type: string -- Examples: [ - "readonly_user", - "reporting_user", -] +- Examples: sprint -#### Attribute `db.jdbc.driver_classname` - -The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. +#### Attribute `network.connection.subtype` +This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. - Requirement Level: Recommended -- Tag: connection-level-tech-specific - -- Type: string -- Examples: [ - "org.postgresql.Driver", - "com.microsoft.sqlserver.jdbc.SQLServerDriver", -] +- Type: Enum [gprs, edge, umts, cdma, evdo_0, evdo_a, cdma2000_1xrtt, hsdpa, hsupa, hspa, iden, evdo_b, lte, ehrpd, hspap, gsm, td_scdma, iwlan, nr, nrnsa, lte_ca] +- Examples: LTE -#### Attribute `db.name` - -This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). - +#### Attribute `network.connection.type` +The internet connection type. -In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -- Requirement Level: Conditionally Required - If applicable. - -- Tag: call-level +- Requirement Level: Recommended -- Type: string -- Examples: [ - "customers", - "main", -] +- Type: Enum [wifi, wired, cell, unavailable, unknown] +- Examples: wifi -#### Attribute `db.statement` - -The database statement being executed. +#### Attribute `network.local.address` +Local address of the network connection - IP address or Unix domain socket name. -- Requirement Level: Optional - -- Tag: call-level +- Requirement Level: Recommended - Type: string - Examples: [ - "SELECT * FROM wuser_table", - "SET mykey \"WuValue\"", + "10.1.2.80", + "/tmp/my.sock", ] +- Stability: Stable -#### Attribute `db.operation` - -The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. - + +#### Attribute `network.local.port` +Local port number of the network connection. -When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. -- Requirement Level: Conditionally Required - If `db.statement` is not applicable. - -- Tag: call-level +- Requirement Level: Recommended -- Type: string +- Type: int - Examples: [ - "findAndModify", - "HMSET", - "SELECT", + 65123, ] +- Stability: Stable -#### Attribute `server.address` - -Name of the database host. - + +#### Attribute `network.peer.address` +Peer address of the network connection - IP address or Unix domain socket name. -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. - Requirement Level: Recommended -- Tag: connection-level - - Type: string - Examples: [ - "example.com", "10.1.2.80", "/tmp/my.sock", ] @@ -1740,58 +1724,51 @@ When observed from the client side, and when communicating through an intermedia - Stability: Stable -#### Attribute `server.port` - -Server port number. +#### Attribute `network.peer.port` +Peer port number of the network connection. -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. -- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. - -- Tag: connection-level +- Requirement Level: Recommended - Type: int - Examples: [ - 80, - 8080, - 443, + 65123, ] - Stability: Stable -#### Attribute `network.peer.address` +#### Attribute `network.protocol.name` + +[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. -Peer address of the network connection - IP address or Unix domain socket name. +The value SHOULD be normalized to lowercase. - Requirement Level: Recommended -- Tag: connection-level - - Type: string - Examples: [ - "10.1.2.80", - "/tmp/my.sock", + "amqp", + "http", + "mqtt", ] - Stability: Stable -#### Attribute `network.peer.port` +#### Attribute `network.protocol.version` -Peer port number of the network connection. +Version of the protocol specified in `network.protocol.name`. -- Requirement Level: Optional - -- Tag: connection-level +`network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +- Requirement Level: Recommended -- Type: int -- Examples: [ - 65123, -] +- Type: string +- Examples: 3.1.1 - Stability: Stable @@ -1810,8 +1787,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. - Requirement Level: Recommended -- Tag: connection-level - - Type: Enum [tcp, udp, pipe, unix] - Examples: [ "tcp", @@ -1830,8 +1805,6 @@ The value SHOULD be normalized to lowercase. - Requirement Level: Recommended -- Tag: connection-level - - Type: Enum [ipv4, ipv6] - Examples: [ "ipv4", @@ -1841,159 +1814,305 @@ The value SHOULD be normalized to lowercase. - Stability: Stable -#### Attribute `db.instance.id` - -An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. +#### Attribute `network.io.direction` +The network IO operation direction. -- Requirement Level: Optional - -- Tag: connection-level +- Requirement Level: Recommended -- Type: string -- Examples: mysql-e26b99z.example.com +- Type: Enum [transmit, receive] +- Examples: [ + "transmit", +] -## Group `db.mssql` (span) +## Group `registry.rpc` (attribute_group) ### Brief -Connection-level attributes for Microsoft SQL Server +This document defines attributes for remote procedure calls. -prefix: +prefix: rpc ### Attributes -#### Attribute `db.system` +#### Attribute `rpc.connect_rpc.error_code` -An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. -- Requirement Level: Required +- Requirement Level: Recommended -- Tag: connection-level +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] -- Type: Enum [other_sql, mssql, mssqlcompact, mysql, oracle, db2, postgresql, redshift, hive, cloudscape, hsqldb, progress, maxdb, hanadb, ingres, firstsql, edb, cache, adabas, firebird, derby, filemaker, informix, instantdb, interbase, mariadb, netezza, pervasive, pointbase, sqlite, sybase, teradata, vertica, h2, coldfusion, cassandra, hbase, mongodb, redis, couchbase, couchdb, cosmosdb, dynamodb, neo4j, geode, elasticsearch, memcached, cockroachdb, opensearch, clickhouse, spanner, trino] +- Stability: Experimental -#### Attribute `db.connection_string` +#### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. -The connection string used to connect to the database. It is recommended to remove embedded credentials. +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. - Requirement Level: Recommended -- Tag: connection-level +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] -- Type: string -- Examples: Server=(localdb)\v11.0;Integrated Security=true; +- Stability: Experimental -#### Attribute `db.user` +#### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. -Username for accessing the database. +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. - Requirement Level: Recommended -- Tag: connection-level - -- Type: string +- Type: template[string[]] - Examples: [ - "readonly_user", - "reporting_user", + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", ] +- Stability: Experimental -#### Attribute `db.jdbc.driver_classname` - -The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. + +#### Attribute `rpc.grpc.status_code` +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. - Requirement Level: Recommended -- Tag: connection-level-tech-specific +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] -- Type: string -- Examples: [ - "org.postgresql.Driver", - "com.microsoft.sqlserver.jdbc.SQLServerDriver", -] +- Stability: Experimental -#### Attribute `db.name` +#### Attribute `rpc.grpc.request.metadata` -This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. -In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). +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. -- Requirement Level: Conditionally Required - If applicable. - -- Tag: call-level +- Requirement Level: Recommended -- Type: string +- Type: template[string[]] - Examples: [ - "customers", - "main", + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", ] +- Stability: Experimental + -#### Attribute `db.statement` +#### Attribute `rpc.grpc.response.metadata` -The database statement being executed. +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. -- Requirement Level: Optional - -- Tag: call-level +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. + +- Requirement Level: Recommended -- Type: string +- Type: template[string[]] - Examples: [ - "SELECT * FROM wuser_table", - "SET mykey \"WuValue\"", + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", ] +- Stability: Experimental -#### Attribute `db.operation` + +#### Attribute `rpc.jsonrpc.error_code` -The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. +`error.code` property of response if it is an error response. +- Requirement Level: Recommended + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. -When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. -- Requirement Level: Conditionally Required - If `db.statement` is not applicable. +- Requirement Level: Recommended -- Tag: call-level +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended - Type: string - Examples: [ - "findAndModify", - "HMSET", - "SELECT", + "10", + "request-7", + "", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "2.0", + "1.0", ] +- Stability: Experimental + -#### Attribute `server.address` +#### Attribute `rpc.method` -Name of the database host. +The name of the (logical) method being called, must be equal to the $method part in the span name. +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -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. +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). - Requirement Level: Recommended -- Tag: connection-level +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Recommended + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +#### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + + +## Group `server` (attribute_group) + +### Brief + +These attributes may be used to describe the server in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +prefix: server + +### Attributes + + +#### Attribute `server.address` + +Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended - Type: string - Examples: [ @@ -2012,9 +2131,7 @@ Server port number. 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. -- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. - -- Tag: connection-level +- Requirement Level: Recommended - Type: int - Examples: [ @@ -2026,122 +2143,137 @@ When observed from the client side, and when communicating through an intermedia - Stability: Stable -#### Attribute `network.peer.address` -Peer address of the network connection - IP address or Unix domain socket name. +## Group `registry.url` (attribute_group) + +### Brief + +Attributes describing URL. + +prefix: url + +### Attributes + + +#### Attribute `url.scheme` + +The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. - Requirement Level: Recommended -- Tag: connection-level - - Type: string - Examples: [ - "10.1.2.80", - "/tmp/my.sock", + "https", + "ftp", + "telnet", ] - Stability: Stable -#### Attribute `network.peer.port` +#### Attribute `url.full` -Peer port number of the network connection. +Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) -- Requirement Level: Optional - -- Tag: connection-level +For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. + +- Requirement Level: Recommended -- Type: int +- Type: string - Examples: [ - 65123, + "https://www.foo.bar/search?q=OpenTelemetry#SemConv", + "//localhost", ] - Stability: Stable -#### Attribute `network.transport` - -[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). - - +#### Attribute `url.path` -The value SHOULD be normalized to lowercase. +The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - Requirement Level: Recommended -- Tag: connection-level - -- Type: Enum [tcp, udp, pipe, unix] +- Type: string - Examples: [ - "tcp", - "udp", + "/search", ] - Stability: Stable -#### Attribute `network.type` +#### Attribute `url.query` -[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. +The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component -The value SHOULD be normalized to lowercase. +Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. - Requirement Level: Recommended -- Tag: connection-level - -- Type: Enum [ipv4, ipv6] +- Type: string - Examples: [ - "ipv4", - "ipv6", + "q=OpenTelemetry", ] - Stability: Stable -#### Attribute `db.instance.id` - -An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. +#### Attribute `url.fragment` +The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component -- Requirement Level: Optional - -- Tag: connection-level +- Requirement Level: Recommended - Type: string -- Examples: mysql-e26b99z.example.com +- Examples: [ + "SemConv", +] + +- Stability: Stable -#### Attribute `db.mssql.instance_name` -The Microsoft SQL Server [instance name](https://docs.microsoft.com/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. +## Group `registry.user_agent` (attribute_group) + +### Brief +Describes user-agent attributes. + +prefix: user_agent + +### Attributes + + +#### Attribute `user_agent.original` + +Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. -If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). - Requirement Level: Recommended -- Tag: connection-level-tech-specific - - Type: string -- Examples: MSSQLSERVER +- Examples: [ + "CERN-LineMode/2.15 libwww/2.17b3", + "Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1", +] + +- Stability: Stable -## Group `db.cassandra` (span) +## Group `db` (span) ### Brief -Call-level attributes for Cassandra +This document defines the attributes used to perform database client calls. prefix: @@ -2208,9 +2340,28 @@ The fully-qualified class name of the [Java Database Connectivity (JDBC)](https: ] -#### Attribute `db.statement` +#### Attribute `db.name` -The database statement being executed. +This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). + + + +In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). + +- Requirement Level: Conditionally Required - If applicable. + +- Tag: call-level + +- Type: string +- Examples: [ + "customers", + "main", +] + + +#### Attribute `db.statement` + +The database statement being executed. @@ -2382,132 +2533,12 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.cassandra.consistency_level` - -The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). - - - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: Enum [all, each_quorum, quorum, local_quorum, one, two, three, local_one, any, serial, local_serial] - - -#### Attribute `db.cassandra.coordinator.dc` - -The data center of the coordinating node for a query. - - - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: string -- Examples: us-west-2 - - -#### Attribute `db.cassandra.coordinator.id` - -The ID of the coordinating node for a query. - - - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: string -- Examples: be13faa2-8574-4d71-926d-27f16cf8a7af - - -#### Attribute `db.cassandra.idempotence` - -Whether or not the query is idempotent. - - - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: boolean - - -#### Attribute `db.cassandra.page_size` - -The fetch size used for paging, i.e. how many rows will be returned at once. - - - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: int -- Examples: [ - 5000, -] - - -#### Attribute `db.cassandra.speculative_execution_count` - -The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. - - - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: int -- Examples: [ - 0, - 2, -] - - -#### Attribute `db.cassandra.table` - -The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). - - -This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. - -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: string -- Examples: mytable - - -#### Attribute `db.name` - -The keyspace name in Cassandra. - - - -For Cassandra the `db.name` should be set to the Cassandra keyspace name. - -- Requirement Level: Conditionally Required - If applicable. - -- Tag: call-level-tech-specific-cassandra - -- Type: string -- Examples: [ - "mykeyspace", -] - - -## Group `db.hbase` (span) +## Group `db.mssql` (span) ### Brief -Call-level attributes for HBase +Connection-level attributes for Microsoft SQL Server prefix: @@ -2574,6 +2605,25 @@ The fully-qualified class name of the [Java Database Connectivity (JDBC)](https: ] +#### Attribute `db.name` + +This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). + + + +In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). + +- Requirement Level: Conditionally Required - If applicable. + +- Tag: call-level + +- Type: string +- Examples: [ + "customers", + "main", +] + + #### Attribute `db.statement` The database statement being executed. @@ -2748,30 +2798,28 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.name` +#### Attribute `db.mssql.instance_name` -The HBase namespace. +The Microsoft SQL Server [instance name](https://docs.microsoft.com/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. -For HBase the `db.name` should be set to the HBase namespace. +If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). -- Requirement Level: Conditionally Required - If applicable. +- Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: connection-level-tech-specific - Type: string -- Examples: [ - "mynamespace", -] +- Examples: MSSQLSERVER -## Group `db.couchdb` (span) +## Group `db.cassandra` (span) ### Brief -Call-level attributes for CouchDB +Call-level attributes for Cassandra prefix: @@ -2838,39 +2886,40 @@ The fully-qualified class name of the [Java Database Connectivity (JDBC)](https: ] -#### Attribute `db.name` - -This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). +#### Attribute `db.statement` +The database statement being executed. -In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -- Requirement Level: Conditionally Required - If applicable. +- Requirement Level: Optional - Tag: call-level - Type: string - Examples: [ - "customers", - "main", + "SELECT * FROM wuser_table", + "SET mykey \"WuValue\"", ] -#### Attribute `db.statement` +#### Attribute `db.operation` -The database statement being executed. +The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. -- Requirement Level: Optional +When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. + +- Requirement Level: Conditionally Required - If `db.statement` is not applicable. - Tag: call-level - Type: string - Examples: [ - "SELECT * FROM wuser_table", - "SET mykey \"WuValue\"", + "findAndModify", + "HMSET", + "SELECT", ] @@ -3011,71 +3060,173 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.operation` - -The HTTP method + the target REST route. +#### Attribute `db.cassandra.consistency_level` +The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). -In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). -- Requirement Level: Conditionally Required - If `db.statement` is not applicable. +- Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: call-level-tech-specific-cassandra -- Type: string -- Examples: [ - "GET /{db}/{docid}", -] +- Type: Enum [all, each_quorum, quorum, local_quorum, one, two, three, local_one, any, serial, local_serial] +#### Attribute `db.cassandra.coordinator.dc` -## Group `db.redis` (span) - -### Brief - -Call-level attributes for Redis - -prefix: - -### Attributes - - -#### Attribute `db.system` +The data center of the coordinating node for a query. -An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. -- Requirement Level: Required +- Requirement Level: Recommended -- Tag: connection-level +- Tag: call-level-tech-specific-cassandra -- Type: Enum [other_sql, mssql, mssqlcompact, mysql, oracle, db2, postgresql, redshift, hive, cloudscape, hsqldb, progress, maxdb, hanadb, ingres, firstsql, edb, cache, adabas, firebird, derby, filemaker, informix, instantdb, interbase, mariadb, netezza, pervasive, pointbase, sqlite, sybase, teradata, vertica, h2, coldfusion, cassandra, hbase, mongodb, redis, couchbase, couchdb, cosmosdb, dynamodb, neo4j, geode, elasticsearch, memcached, cockroachdb, opensearch, clickhouse, spanner, trino] +- Type: string +- Examples: us-west-2 -#### Attribute `db.connection_string` +#### Attribute `db.cassandra.coordinator.id` -The connection string used to connect to the database. It is recommended to remove embedded credentials. +The ID of the coordinating node for a query. - Requirement Level: Recommended -- Tag: connection-level +- Tag: call-level-tech-specific-cassandra - Type: string -- Examples: Server=(localdb)\v11.0;Integrated Security=true; +- Examples: be13faa2-8574-4d71-926d-27f16cf8a7af -#### Attribute `db.user` +#### Attribute `db.cassandra.idempotence` -Username for accessing the database. +Whether or not the query is idempotent. - Requirement Level: Recommended -- Tag: connection-level +- Tag: call-level-tech-specific-cassandra + +- Type: boolean + + +#### Attribute `db.cassandra.page_size` + +The fetch size used for paging, i.e. how many rows will be returned at once. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: int +- Examples: [ + 5000, +] + + +#### Attribute `db.cassandra.speculative_execution_count` + +The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: int +- Examples: [ + 0, + 2, +] + + +#### Attribute `db.cassandra.table` + +The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). + + +This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: string +- Examples: mytable + + +#### Attribute `db.name` + +The keyspace name in Cassandra. + + + +For Cassandra the `db.name` should be set to the Cassandra keyspace name. + +- Requirement Level: Conditionally Required - If applicable. + +- Tag: call-level-tech-specific-cassandra + +- Type: string +- Examples: [ + "mykeyspace", +] + + + +## Group `db.hbase` (span) + +### Brief + +Call-level attributes for HBase + +prefix: + +### Attributes + + +#### Attribute `db.system` + +An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Tag: connection-level + +- Type: Enum [other_sql, mssql, mssqlcompact, mysql, oracle, db2, postgresql, redshift, hive, cloudscape, hsqldb, progress, maxdb, hanadb, ingres, firstsql, edb, cache, adabas, firebird, derby, filemaker, informix, instantdb, interbase, mariadb, netezza, pervasive, pointbase, sqlite, sybase, teradata, vertica, h2, coldfusion, cassandra, hbase, mongodb, redis, couchbase, couchdb, cosmosdb, dynamodb, neo4j, geode, elasticsearch, memcached, cockroachdb, opensearch, clickhouse, spanner, trino] + + +#### Attribute `db.connection_string` + +The connection string used to connect to the database. It is recommended to remove embedded credentials. + + + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: string +- Examples: Server=(localdb)\v11.0;Integrated Security=true; + + +#### Attribute `db.user` + +Username for accessing the database. + + + +- Requirement Level: Recommended + +- Tag: connection-level - Type: string - Examples: [ @@ -3101,22 +3252,20 @@ The fully-qualified class name of the [Java Database Connectivity (JDBC)](https: ] -#### Attribute `db.name` - -This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). +#### Attribute `db.statement` +The database statement being executed. -In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -- Requirement Level: Conditionally Required - If applicable. +- Requirement Level: Optional - Tag: call-level - Type: string - Examples: [ - "customers", - "main", + "SELECT * FROM wuser_table", + "SET mykey \"WuValue\"", ] @@ -3277,48 +3426,30 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.redis.database_index` - -The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. - - - -- Requirement Level: Conditionally Required - If other than the default database (`0`). - -- Tag: call-level-tech-specific - -- Type: int -- Examples: [ - 0, - 1, - 15, -] - - -#### Attribute `db.statement` +#### Attribute `db.name` -The full syntax of the Redis CLI command. +The HBase namespace. -For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. +For HBase the `db.name` should be set to the HBase namespace. -- Requirement Level: Optional +- Requirement Level: Conditionally Required - If applicable. - Tag: call-level-tech-specific - Type: string - Examples: [ - "HMSET myhash field1 'Hello' field2 'World'", + "mynamespace", ] -## Group `db.mongodb` (span) +## Group `db.couchdb` (span) ### Brief -Call-level attributes for MongoDB +Call-level attributes for CouchDB prefix: @@ -3421,26 +3552,6 @@ The database statement being executed. ] -#### Attribute `db.operation` - -The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. - - - -When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. - -- Requirement Level: Conditionally Required - If `db.statement` is not applicable. - -- Tag: call-level - -- Type: string -- Examples: [ - "findAndModify", - "HMSET", - "SELECT", -] - - #### Attribute `server.address` Name of the database host. @@ -3578,29 +3689,30 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.mongodb.collection` +#### Attribute `db.operation` -The MongoDB collection being accessed within the database stated in `db.name`. +The HTTP method + the target REST route. -- Requirement Level: Required +In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). + +- Requirement Level: Conditionally Required - If `db.statement` is not applicable. - Tag: call-level-tech-specific - Type: string - Examples: [ - "customers", - "products", + "GET /{db}/{docid}", ] -## Group `db.elasticsearch` (span) +## Group `db.redis` (span) ### Brief -Call-level attributes for Elasticsearch +Call-level attributes for Redis prefix: @@ -3686,17 +3798,41 @@ In some SQL databases, the database name to be used is called "schema name". In ] -#### Attribute `network.peer.address` +#### Attribute `db.operation` -Peer address of the network connection - IP address or Unix domain socket name. +The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. + + + +When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. + +- Requirement Level: Conditionally Required - If `db.statement` is not applicable. + +- Tag: call-level + +- Type: string +- Examples: [ + "findAndModify", + "HMSET", + "SELECT", +] + + +#### Attribute `server.address` + +Name of the database host. + +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. + - Requirement Level: Recommended - Tag: connection-level - Type: string - Examples: [ + "example.com", "10.1.2.80", "/tmp/my.sock", ] @@ -3704,271 +3840,163 @@ Peer address of the network connection - IP address or Unix domain socket name. - Stability: Stable -#### Attribute `network.peer.port` +#### Attribute `server.port` -Peer port number of the network connection. +Server port number. -- Requirement Level: Optional +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. + +- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. - Tag: connection-level - Type: int - Examples: [ - 65123, + 80, + 8080, + 443, ] - Stability: Stable -#### Attribute `network.transport` - -[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). - - +#### Attribute `network.peer.address` -The value SHOULD be normalized to lowercase. +Peer address of the network connection - IP address or Unix domain socket name. -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - Requirement Level: Recommended - Tag: connection-level -- Type: Enum [tcp, udp, pipe, unix] +- Type: string - Examples: [ - "tcp", - "udp", + "10.1.2.80", + "/tmp/my.sock", ] - Stability: Stable -#### Attribute `network.type` - -[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. - - -The value SHOULD be normalized to lowercase. - -- Requirement Level: Recommended - -- Tag: connection-level - -- Type: Enum [ipv4, ipv6] -- Examples: [ - "ipv4", - "ipv6", -] - -- Stability: Stable - - -#### Attribute `db.instance.id` - -An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. +#### Attribute `network.peer.port` +Peer port number of the network connection. - Requirement Level: Optional - Tag: connection-level -- Type: string -- Examples: mysql-e26b99z.example.com - - -#### Attribute `db.elasticsearch.cluster.name` - -Represents the identifier of an Elasticsearch cluster. - - - -- Requirement Level: Optional - -- Tag: call-level-tech-specific - -- Type: string +- Type: int - Examples: [ - "e9106fc68e3044f0b1475b04bf4ffd5f", + 65123, ] - -#### Attribute `db.elasticsearch.node.name` - -Represents the human-readable identifier of the node/instance to which a request was routed. - - - -- Requirement Level: Optional - -- Tag: call-level-tech-specific - -- Type: string -- Examples: [ - "instance-0000000001", -] +- Stability: Stable -#### Attribute `db.elasticsearch.path_parts` - -A dynamic value in the url path. - - +#### Attribute `network.transport` -Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). -- Requirement Level: Conditionally Required - when the url has dynamic values - -- Tag: call-level-tech-specific - -- Type: template[string] -- Examples: [ - "db.elasticsearch.path_parts.index=test-index", - "db.elasticsearch.path_parts.doc_id=123", -] - - -#### Attribute `db.operation` -The endpoint identifier for the request. +The value SHOULD be normalized to lowercase. -When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. -- Requirement Level: Required +- Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: connection-level -- Type: string +- Type: Enum [tcp, udp, pipe, unix] - Examples: [ - "search", - "ml.close_job", - "cat.aliases", + "tcp", + "udp", ] - -#### Attribute `db.statement` - -The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. - - -- Requirement Level: Optional - -- Tag: call-level-tech-specific - -- Type: string -- Examples: [ - "\"{\\\"query\\\":{\\\"term\\\":{\\\"user.id\\\":\\\"kimchy\\\"}}}\"", -] +- Stability: Stable -#### Attribute `http.request.method` - -HTTP request method. - - -HTTP request method value SHOULD be "known" to the instrumentation. -By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +#### Attribute `network.type` -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. -If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override -the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named -OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods -(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. -Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. -Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +The value SHOULD be normalized to lowercase. -- Requirement Level: Required +- Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: connection-level -- Type: Enum [CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE, _OTHER] +- Type: Enum [ipv4, ipv6] - Examples: [ - "GET", - "POST", - "HEAD", + "ipv4", + "ipv6", ] - Stability: Stable -#### Attribute `server.address` - -Name of the database host. +#### Attribute `db.instance.id` +An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. -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. -- Requirement Level: Recommended +- Requirement Level: Optional -- Tag: call-level-tech-specific +- Tag: connection-level - Type: string -- Examples: [ - "example.com", - "10.1.2.80", - "/tmp/my.sock", -] - -- Stability: Stable +- Examples: mysql-e26b99z.example.com -#### Attribute `server.port` +#### Attribute `db.redis.database_index` -Server port number. +The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. -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. -- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. +- Requirement Level: Conditionally Required - If other than the default database (`0`). - Tag: call-level-tech-specific - Type: int - Examples: [ - 80, - 8080, - 443, + 0, + 1, + 15, ] -- Stability: Stable - -#### Attribute `url.full` +#### Attribute `db.statement` -Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) +The full syntax of the Redis CLI command. -For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. -- Requirement Level: Required +For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. + +- Requirement Level: Optional - Tag: call-level-tech-specific - Type: string - Examples: [ - "https://localhost:9200/index/_search?q=user.id:kimchy", + "HMSET myhash field1 'Hello' field2 'World'", ] -- Stability: Stable - -## Group `db.sql` (span) +## Group `db.mongodb` (span) ### Brief -Call-level attributes for SQL databases +Call-level attributes for MongoDB prefix: @@ -4228,32 +4256,31 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.sql.table` +#### Attribute `db.mongodb.collection` -The name of the primary table that the operation is acting upon, including the database name (if applicable). +The MongoDB collection being accessed within the database stated in `db.name`. -It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. -- Requirement Level: Recommended +- Requirement Level: Required - Tag: call-level-tech-specific - Type: string - Examples: [ - "public.users", "customers", + "products", ] -## Group `db.cosmosdb` (span) +## Group `db.elasticsearch` (span) ### Brief -Call-level attributes for Cosmos DB. +Call-level attributes for Elasticsearch -prefix: db.cosmosdb +prefix: ### Attributes @@ -4337,317 +4364,289 @@ In some SQL databases, the database name to be used is called "schema name". In ] -#### Attribute `db.statement` - -The database statement being executed. +#### Attribute `network.peer.address` +Peer address of the network connection - IP address or Unix domain socket name. -- Requirement Level: Optional +- Requirement Level: Recommended -- Tag: call-level +- Tag: connection-level - Type: string - Examples: [ - "SELECT * FROM wuser_table", - "SET mykey \"WuValue\"", + "10.1.2.80", + "/tmp/my.sock", ] +- Stability: Stable -#### Attribute `db.operation` - -The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. - + +#### Attribute `network.peer.port` +Peer port number of the network connection. -When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. -- Requirement Level: Conditionally Required - If `db.statement` is not applicable. +- Requirement Level: Optional -- Tag: call-level +- Tag: connection-level -- Type: string +- Type: int - Examples: [ - "findAndModify", - "HMSET", - "SELECT", + 65123, ] +- Stability: Stable + -#### Attribute `server.address` +#### Attribute `network.transport` -Name of the database host. +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). -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. +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. - Requirement Level: Recommended - Tag: connection-level -- Type: string +- Type: Enum [tcp, udp, pipe, unix] - Examples: [ - "example.com", - "10.1.2.80", - "/tmp/my.sock", + "tcp", + "udp", ] - Stability: Stable -#### Attribute `server.port` +#### Attribute `network.type` -Server port number. +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. -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. +The value SHOULD be normalized to lowercase. -- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. +- Requirement Level: Recommended - Tag: connection-level -- Type: int +- Type: Enum [ipv4, ipv6] - Examples: [ - 80, - 8080, - 443, + "ipv4", + "ipv6", ] - Stability: Stable -#### Attribute `network.peer.address` +#### Attribute `db.instance.id` -Peer address of the network connection - IP address or Unix domain socket name. +An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. -- Requirement Level: Recommended + +- Requirement Level: Optional - Tag: connection-level - Type: string -- Examples: [ - "10.1.2.80", - "/tmp/my.sock", -] - -- Stability: Stable +- Examples: mysql-e26b99z.example.com -#### Attribute `network.peer.port` +#### Attribute `db.elasticsearch.cluster.name` + +Represents the identifier of an Elasticsearch cluster. -Peer port number of the network connection. - Requirement Level: Optional -- Tag: connection-level +- Tag: call-level-tech-specific -- Type: int +- Type: string - Examples: [ - 65123, + "e9106fc68e3044f0b1475b04bf4ffd5f", ] -- Stability: Stable - -#### Attribute `network.transport` - -[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). - +#### Attribute `db.elasticsearch.node.name` +Represents the human-readable identifier of the node/instance to which a request was routed. -The value SHOULD be normalized to lowercase. -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. -- Requirement Level: Recommended +- Requirement Level: Optional -- Tag: connection-level +- Tag: call-level-tech-specific -- Type: Enum [tcp, udp, pipe, unix] +- Type: string - Examples: [ - "tcp", - "udp", + "instance-0000000001", ] -- Stability: Stable - -#### Attribute `network.type` +#### Attribute `db.elasticsearch.path_parts` -[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. +A dynamic value in the url path. -The value SHOULD be normalized to lowercase. -- Requirement Level: Recommended +Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +- Requirement Level: Conditionally Required - when the url has dynamic values -- Tag: connection-level +- Tag: call-level-tech-specific -- Type: Enum [ipv4, ipv6] +- Type: template[string] - Examples: [ - "ipv4", - "ipv6", + "db.elasticsearch.path_parts.index=test-index", + "db.elasticsearch.path_parts.doc_id=123", ] -- Stability: Stable - -#### Attribute `db.instance.id` - -An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. - - +#### Attribute `db.operation` -- Requirement Level: Optional - -- Tag: connection-level - -- Type: string -- Examples: mysql-e26b99z.example.com - - -#### Attribute `db.cosmosdb.client_id` +The endpoint identifier for the request. -Unique Cosmos client instance id. +When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. -- Requirement Level: Recommended +- Requirement Level: Required - Tag: call-level-tech-specific - Type: string -- Examples: 3ba4827d-4422-483f-b59f-85b74211c11d - - -#### Attribute `db.cosmosdb.connection_mode` - -Cosmos client connection mode. - - -- Requirement Level: Conditionally Required - if not `direct` (or pick gw as default) - -- Tag: call-level-tech-specific - -- Type: Enum [gateway, direct] +- Examples: [ + "search", + "ml.close_job", + "cat.aliases", +] -#### Attribute `db.cosmosdb.container` +#### Attribute `db.statement` -Cosmos DB container name. +The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. -- Requirement Level: Conditionally Required - if available +- Requirement Level: Optional - Tag: call-level-tech-specific - Type: string -- Examples: anystring +- Examples: [ + "\"{\\\"query\\\":{\\\"term\\\":{\\\"user.id\\\":\\\"kimchy\\\"}}}\"", +] -#### Attribute `db.cosmosdb.operation_type` +#### Attribute `http.request.method` -CosmosDB Operation Type. +HTTP request method. -- Requirement Level: Conditionally Required - when performing one of the operations in this list - -- Tag: call-level-tech-specific - -- Type: Enum [Invalid, Create, Patch, Read, ReadFeed, Delete, Replace, Execute, Query, Head, HeadFeed, Upsert, Batch, QueryPlan, ExecuteJavaScript] - - -#### Attribute `db.cosmosdb.request_charge` +HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -RU consumed for that operation +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -- Requirement Level: Conditionally Required - when available +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +- Requirement Level: Required - Tag: call-level-tech-specific -- Type: double +- Type: Enum [CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE, _OTHER] - Examples: [ - 46.18, - 1.0, + "GET", + "POST", + "HEAD", ] +- Stability: Stable -#### Attribute `db.cosmosdb.request_content_length` - -Request payload size in bytes + +#### Attribute `server.address` +Name of the database host. -- Requirement Level: Recommended - -- Tag: call-level-tech-specific - -- Type: int - - -#### Attribute `db.cosmosdb.status_code` -Cosmos DB status code. +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. -- Requirement Level: Conditionally Required - if response was received +- Requirement Level: Recommended - Tag: call-level-tech-specific -- Type: int +- Type: string - Examples: [ - 200, - 201, + "example.com", + "10.1.2.80", + "/tmp/my.sock", ] +- Stability: Stable -#### Attribute `db.cosmosdb.sub_status_code` + +#### Attribute `server.port` -Cosmos DB sub status code. +Server port number. -- Requirement Level: Conditionally Required - when response was received and contained sub-code. +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. + +- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. - Tag: call-level-tech-specific - Type: int - Examples: [ - 1000, - 1002, + 80, + 8080, + 443, ] +- Stability: Stable + -#### Attribute `user_agent.original` +#### Attribute `url.full` -Full user-agent string is generated by Cosmos DB SDK +Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) -The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. - Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). - Default value is "NS". +For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. -- Requirement Level: Recommended +- Requirement Level: Required - Tag: call-level-tech-specific - Type: string - Examples: [ - "cosmos-netstandard-sdk/3.23.0\\|3.23.1\\|1\\|X64\\|Linux 5.4.0-1098-azure 104 18\\|.NET Core 3.1.32\\|S\\|", + "https://localhost:9200/index/_search?q=user.id:kimchy", ] - Stability: Stable -## Group `db.tech` (span) +## Group `db.sql` (span) ### Brief -Semantic convention group for specific technologies +Call-level attributes for SQL databases prefix: @@ -4907,196 +4906,288 @@ An identifier (address, unique name, or any other identifier) of the database in - Examples: mysql-e26b99z.example.com -#### Attribute `db.cassandra.consistency_level` +#### Attribute `db.sql.table` -The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). +The name of the primary table that the operation is acting upon, including the database name (if applicable). +It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. - Requirement Level: Recommended -- Tag: call-level-tech-specific-cassandra +- Tag: call-level-tech-specific -- Type: Enum [all, each_quorum, quorum, local_quorum, one, two, three, local_one, any, serial, local_serial] +- Type: string +- Examples: [ + "public.users", + "customers", +] -#### Attribute `db.cassandra.coordinator.dc` -The data center of the coordinating node for a query. +## Group `db.cosmosdb` (span) +### Brief +Call-level attributes for Cosmos DB. -- Requirement Level: Recommended - -- Tag: call-level-tech-specific-cassandra - -- Type: string -- Examples: us-west-2 - - -#### Attribute `db.cassandra.coordinator.id` +prefix: db.cosmosdb -The ID of the coordinating node for a query. +### Attributes + + +#### Attribute `db.system` + +An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Tag: connection-level + +- Type: Enum [other_sql, mssql, mssqlcompact, mysql, oracle, db2, postgresql, redshift, hive, cloudscape, hsqldb, progress, maxdb, hanadb, ingres, firstsql, edb, cache, adabas, firebird, derby, filemaker, informix, instantdb, interbase, mariadb, netezza, pervasive, pointbase, sqlite, sybase, teradata, vertica, h2, coldfusion, cassandra, hbase, mongodb, redis, couchbase, couchdb, cosmosdb, dynamodb, neo4j, geode, elasticsearch, memcached, cockroachdb, opensearch, clickhouse, spanner, trino] + + +#### Attribute `db.connection_string` + +The connection string used to connect to the database. It is recommended to remove embedded credentials. - Requirement Level: Recommended -- Tag: call-level-tech-specific-cassandra +- Tag: connection-level - Type: string -- Examples: be13faa2-8574-4d71-926d-27f16cf8a7af +- Examples: Server=(localdb)\v11.0;Integrated Security=true; -#### Attribute `db.cassandra.idempotence` +#### Attribute `db.user` -Whether or not the query is idempotent. +Username for accessing the database. - Requirement Level: Recommended -- Tag: call-level-tech-specific-cassandra +- Tag: connection-level -- Type: boolean +- Type: string +- Examples: [ + "readonly_user", + "reporting_user", +] -#### Attribute `db.cassandra.page_size` +#### Attribute `db.jdbc.driver_classname` -The fetch size used for paging, i.e. how many rows will be returned at once. +The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. - Requirement Level: Recommended -- Tag: call-level-tech-specific-cassandra +- Tag: connection-level-tech-specific -- Type: int +- Type: string - Examples: [ - 5000, + "org.postgresql.Driver", + "com.microsoft.sqlserver.jdbc.SQLServerDriver", ] -#### Attribute `db.cassandra.speculative_execution_count` +#### Attribute `db.name` -The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. +This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). -- Requirement Level: Recommended +In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). + +- Requirement Level: Conditionally Required - If applicable. -- Tag: call-level-tech-specific-cassandra +- Tag: call-level -- Type: int +- Type: string - Examples: [ - 0, - 2, + "customers", + "main", ] -#### Attribute `db.cassandra.table` +#### Attribute `db.statement` -The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). +The database statement being executed. -This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. -- Requirement Level: Recommended +- Requirement Level: Optional -- Tag: call-level-tech-specific-cassandra +- Tag: call-level - Type: string -- Examples: mytable +- Examples: [ + "SELECT * FROM wuser_table", + "SET mykey \"WuValue\"", +] -#### Attribute `db.name` +#### Attribute `db.operation` -The keyspace name in Cassandra. +The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. -For Cassandra the `db.name` should be set to the Cassandra keyspace name. +When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. -- Requirement Level: Conditionally Required - If applicable. +- Requirement Level: Conditionally Required - If `db.statement` is not applicable. -- Tag: call-level-tech-specific-cassandra +- Tag: call-level - Type: string - Examples: [ - "mykeyspace", + "findAndModify", + "HMSET", + "SELECT", ] -#### Attribute `db.redis.database_index` +#### Attribute `server.address` -The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. +Name of the database host. -- Requirement Level: Conditionally Required - If other than the default database (`0`). +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. + +- Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: connection-level + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. + +- Tag: connection-level - Type: int - Examples: [ - 0, - 1, - 15, + 80, + 8080, + 443, ] +- Stability: Stable -#### Attribute `db.statement` + +#### Attribute `network.peer.address` -The full syntax of the Redis CLI command. +Peer address of the network connection - IP address or Unix domain socket name. +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. -For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. - Requirement Level: Optional -- Tag: call-level-tech-specific +- Tag: connection-level -- Type: string +- Type: int - Examples: [ - "HMSET myhash field1 'Hello' field2 'World'", + 65123, ] +- Stability: Stable + -#### Attribute `db.mongodb.collection` +#### Attribute `network.transport` -The MongoDB collection being accessed within the database stated in `db.name`. +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). -- Requirement Level: Required +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: connection-level -- Type: string +- Type: Enum [tcp, udp, pipe, unix] - Examples: [ - "customers", - "products", + "tcp", + "udp", ] +- Stability: Stable + -#### Attribute `db.sql.table` +#### Attribute `network.type` -The name of the primary table that the operation is acting upon, including the database name (if applicable). +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. -It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. +The value SHOULD be normalized to lowercase. - Requirement Level: Recommended -- Tag: call-level-tech-specific +- Tag: connection-level -- Type: string +- Type: Enum [ipv4, ipv6] - Examples: [ - "public.users", - "customers", + "ipv4", + "ipv6", ] +- Stability: Stable + + +#### Attribute `db.instance.id` + +An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. + + + +- Requirement Level: Optional + +- Tag: connection-level + +- Type: string +- Examples: mysql-e26b99z.example.com + #### Attribute `db.cosmosdb.client_id` @@ -5229,3 +5320,2217 @@ The user-agent value is generated by SDK which is a combination of
`sdk_vers - Stability: Stable + +## Group `db.tech` (span) + +### Brief + +Semantic convention group for specific technologies + +prefix: + +### Attributes + + +#### Attribute `db.system` + +An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Tag: connection-level + +- Type: Enum [other_sql, mssql, mssqlcompact, mysql, oracle, db2, postgresql, redshift, hive, cloudscape, hsqldb, progress, maxdb, hanadb, ingres, firstsql, edb, cache, adabas, firebird, derby, filemaker, informix, instantdb, interbase, mariadb, netezza, pervasive, pointbase, sqlite, sybase, teradata, vertica, h2, coldfusion, cassandra, hbase, mongodb, redis, couchbase, couchdb, cosmosdb, dynamodb, neo4j, geode, elasticsearch, memcached, cockroachdb, opensearch, clickhouse, spanner, trino] + + +#### Attribute `db.connection_string` + +The connection string used to connect to the database. It is recommended to remove embedded credentials. + + + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: string +- Examples: Server=(localdb)\v11.0;Integrated Security=true; + + +#### Attribute `db.user` + +Username for accessing the database. + + + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: string +- Examples: [ + "readonly_user", + "reporting_user", +] + + +#### Attribute `db.jdbc.driver_classname` + +The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. + + + +- Requirement Level: Recommended + +- Tag: connection-level-tech-specific + +- Type: string +- Examples: [ + "org.postgresql.Driver", + "com.microsoft.sqlserver.jdbc.SQLServerDriver", +] + + +#### Attribute `db.name` + +This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). + + + +In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). + +- Requirement Level: Conditionally Required - If applicable. + +- Tag: call-level + +- Type: string +- Examples: [ + "customers", + "main", +] + + +#### Attribute `db.statement` + +The database statement being executed. + + + +- Requirement Level: Optional + +- Tag: call-level + +- Type: string +- Examples: [ + "SELECT * FROM wuser_table", + "SET mykey \"WuValue\"", +] + + +#### Attribute `db.operation` + +The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. + + + +When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. + +- Requirement Level: Conditionally Required - If `db.statement` is not applicable. + +- Tag: call-level + +- Type: string +- Examples: [ + "findAndModify", + "HMSET", + "SELECT", +] + + +#### Attribute `server.address` + +Name of the database host. + + + +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. + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - If using a port other than the default port for this DBMS and if `server.address` is set. + +- Tag: connection-level + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Tag: connection-level + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Tag: connection-level + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `db.instance.id` + +An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. + + + +- Requirement Level: Optional + +- Tag: connection-level + +- Type: string +- Examples: mysql-e26b99z.example.com + + +#### Attribute `db.cassandra.consistency_level` + +The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: Enum [all, each_quorum, quorum, local_quorum, one, two, three, local_one, any, serial, local_serial] + + +#### Attribute `db.cassandra.coordinator.dc` + +The data center of the coordinating node for a query. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: string +- Examples: us-west-2 + + +#### Attribute `db.cassandra.coordinator.id` + +The ID of the coordinating node for a query. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: string +- Examples: be13faa2-8574-4d71-926d-27f16cf8a7af + + +#### Attribute `db.cassandra.idempotence` + +Whether or not the query is idempotent. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: boolean + + +#### Attribute `db.cassandra.page_size` + +The fetch size used for paging, i.e. how many rows will be returned at once. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: int +- Examples: [ + 5000, +] + + +#### Attribute `db.cassandra.speculative_execution_count` + +The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. + + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: int +- Examples: [ + 0, + 2, +] + + +#### Attribute `db.cassandra.table` + +The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). + + +This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific-cassandra + +- Type: string +- Examples: mytable + + +#### Attribute `db.name` + +The keyspace name in Cassandra. + + + +For Cassandra the `db.name` should be set to the Cassandra keyspace name. + +- Requirement Level: Conditionally Required - If applicable. + +- Tag: call-level-tech-specific-cassandra + +- Type: string +- Examples: [ + "mykeyspace", +] + + +#### Attribute `db.redis.database_index` + +The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. + + + +- Requirement Level: Conditionally Required - If other than the default database (`0`). + +- Tag: call-level-tech-specific + +- Type: int +- Examples: [ + 0, + 1, + 15, +] + + +#### Attribute `db.statement` + +The full syntax of the Redis CLI command. + + + +For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. + +- Requirement Level: Optional + +- Tag: call-level-tech-specific + +- Type: string +- Examples: [ + "HMSET myhash field1 'Hello' field2 'World'", +] + + +#### Attribute `db.mongodb.collection` + +The MongoDB collection being accessed within the database stated in `db.name`. + + + +- Requirement Level: Required + +- Tag: call-level-tech-specific + +- Type: string +- Examples: [ + "customers", + "products", +] + + +#### Attribute `db.sql.table` + +The name of the primary table that the operation is acting upon, including the database name (if applicable). + + +It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific + +- Type: string +- Examples: [ + "public.users", + "customers", +] + + +#### Attribute `db.cosmosdb.client_id` + +Unique Cosmos client instance id. + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific + +- Type: string +- Examples: 3ba4827d-4422-483f-b59f-85b74211c11d + + +#### Attribute `db.cosmosdb.connection_mode` + +Cosmos client connection mode. + + +- Requirement Level: Conditionally Required - if not `direct` (or pick gw as default) + +- Tag: call-level-tech-specific + +- Type: Enum [gateway, direct] + + +#### Attribute `db.cosmosdb.container` + +Cosmos DB container name. + + +- Requirement Level: Conditionally Required - if available + +- Tag: call-level-tech-specific + +- Type: string +- Examples: anystring + + +#### Attribute `db.cosmosdb.operation_type` + +CosmosDB Operation Type. + + +- Requirement Level: Conditionally Required - when performing one of the operations in this list + +- Tag: call-level-tech-specific + +- Type: Enum [Invalid, Create, Patch, Read, ReadFeed, Delete, Replace, Execute, Query, Head, HeadFeed, Upsert, Batch, QueryPlan, ExecuteJavaScript] + + +#### Attribute `db.cosmosdb.request_charge` + +RU consumed for that operation + + +- Requirement Level: Conditionally Required - when available + +- Tag: call-level-tech-specific + +- Type: double +- Examples: [ + 46.18, + 1.0, +] + + +#### Attribute `db.cosmosdb.request_content_length` + +Request payload size in bytes + + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific + +- Type: int + + +#### Attribute `db.cosmosdb.status_code` + +Cosmos DB status code. + + +- Requirement Level: Conditionally Required - if response was received + +- Tag: call-level-tech-specific + +- Type: int +- Examples: [ + 200, + 201, +] + + +#### Attribute `db.cosmosdb.sub_status_code` + +Cosmos DB sub status code. + + +- Requirement Level: Conditionally Required - when response was received and contained sub-code. + +- Tag: call-level-tech-specific + +- Type: int +- Examples: [ + 1000, + 1002, +] + + +#### Attribute `user_agent.original` + +Full user-agent string is generated by Cosmos DB SDK + + +The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. + Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). + Default value is "NS". + +- Requirement Level: Recommended + +- Tag: call-level-tech-specific + +- Type: string +- Examples: [ + "cosmos-netstandard-sdk/3.23.0\\|3.23.1\\|1\\|X64\\|Linux 5.4.0-1098-azure 104 18\\|.NET Core 3.1.32\\|S\\|", +] + +- Stability: Stable + + + +## Group `trace-exception` (event) + +### Brief + +This document defines the attributes used to report a single exception associated with a span. + +prefix: exception + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `exception.stacktrace` + +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. + + + +- Requirement Level: Recommended + +- Type: string +- 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) + +- Stability: Stable + + +#### Attribute `exception.escaped` + +SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. + + + +An exception is considered to have escaped (or left) the scope of a span, +if that span is ended while the exception is still logically "in flight". +This may be actually "in flight" in some languages (e.g. if the exception +is passed to a Context manager's `__exit__` method in Python) but will +usually be caught at the point of recording the exception in most languages. + +It is usually not possible to determine at the point where an exception is thrown +whether it will escape the scope of a span. +However, it is trivial to know that an exception +will escape, if one checks for an active exception just before ending the span, +as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + +It follows that an exception may still escape the scope of the span +even if the `exception.escaped` attribute was not set or set to false, +since the event might have been recorded at a time where it was not +clear whether the exception will escape. + +- Requirement Level: Recommended + +- Type: boolean + +- Stability: Stable + + +#### Attribute `exception.type` + +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. + + + +- Requirement Level: Conditionally Required - Required if `exception.message` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "java.net.ConnectException", + "OSError", +] + +- Stability: Stable + + +#### Attribute `exception.message` + +The exception message. + + +- Requirement Level: Conditionally Required - Required if `exception.type` is not set, recommended otherwise. + +- Type: string +- Examples: [ + "Division by zero", + "Can't convert 'int' object to str implicitly", +] + +- Stability: Stable + + + +## Group `feature_flag` (event) + +### Brief + +This semantic convention defines the attributes used to represent a feature flag evaluation as an event. + +prefix: feature_flag + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `feature_flag.key` + +The unique identifier of the feature flag. + + +- Requirement Level: Required + +- Type: string +- Examples: [ + "logo-color", +] + + +#### Attribute `feature_flag.provider_name` + +The name of the service provider that performs the flag evaluation. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "Flag Manager", +] + + +#### Attribute `feature_flag.variant` + +SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. + + + +A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +A stringified version of the value can be used in situations where a +semantic identifier is unavailable. String representation of the value +should be determined by the implementer. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "red", + "true", + "on", +] + + + +## Group `trace.gen_ai.client` (span) + +### Brief + +Describes GenAI operation span. + +prefix: + +### Attributes + + +#### Attribute `gen_ai.request.max_tokens` + +The maximum number of tokens the model generates for a request. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.temperature` + +The temperature setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_p` + +The top_p sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Tag: llm-generic-request + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_k` + +The top_k sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.stop_sequences` + +List of sequences that the model will use to stop generating further tokens. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "forest", + "lived", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.frequency_penalty` + +The frequency penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.presence_penalty` + +The presence penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.id` + +The unique identifier for the completion. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.finish_reasons` + +Array of reasons the model stopped generating tokens, corresponding to each generation received. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.input_tokens` + +The number of tokens used in the GenAI input (prompt). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.output_tokens` + +The number of tokens used in the GenAI response (completion). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +- Requirement Level: Required + +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai + +- Stability: Experimental + + +#### Attribute `gen_ai.request.model` + +The name of the GenAI model a request is being made to. + + +The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Required + +- Type: string +- Examples: gpt-4 + +- Stability: Experimental + + +#### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Required + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.model` + +The name of the model that generated the response. + + +If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental + + + +## Group `gen_ai.content.prompt` (event) + +### Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +prefix: + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `gen_ai.prompt` + +The full prompt sent to the GenAI model. + + +It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]", +] + +- Stability: Experimental + + + +## Group `gen_ai.content.completion` (event) + +### Brief + +In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation. + +prefix: + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `gen_ai.completion` + +The full response received from the GenAI model. + + +It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + +- Requirement Level: Conditionally Required - if and only if corresponding event is enabled + +- Type: string +- Examples: [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]", +] + +- Stability: Experimental + + + +## Group `rpc` (span) + +### Brief + +This document defines semantic conventions for remote procedure calls. + +prefix: rpc + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + + +## Group `rpc.client` (span) + +### Brief + +This document defines semantic conventions for remote procedure call client spans. + +prefix: + +### Attributes + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Group `rpc.server` (span) + +### Brief + +Semantic Convention for RPC server spans + +prefix: + +### Attributes + + +#### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Group `rpc.grpc` (span) + +### Brief + +Tech-specific attributes for gRPC. + +prefix: + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Required + +- Tag: grpc-tech-specific + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + + +## Group `rpc.jsonrpc` (span) + +### Brief + +Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/). + +prefix: rpc.jsonrpc + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Conditionally Required - If response is not successful. + +- Tag: jsonrpc-tech-specific + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Conditionally Required - If other than the default version (`1.0`) + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is always required for jsonrpc. See the note in the general RPC conventions for more information. + +- Requirement Level: Required + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + + +## Group `rpc.message` (event) + +### Brief + +RPC received/sent message. + +prefix: rpc.message + +### Body Fields + +No event body defined. + +### Attributes + + +#### Attribute `rpc.message.type` + +Whether this is a received or sent message. + + +- Requirement Level: Recommended + +- Type: Enum [SENT, RECEIVED] + +- Stability: Experimental + + +#### Attribute `rpc.message.id` + +MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. + + +This way we guarantee that the values will be consistent between different implementations. + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.compressed_size` + +Compressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + +#### Attribute `rpc.message.uncompressed_size` + +Uncompressed size of the message in bytes. + + +- Requirement Level: Recommended + +- Type: int + +- Stability: Experimental + + + +## Group `rpc.connect_rpc` (span) + +### Brief + +Tech-specific attributes for Connect RPC. + +prefix: + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Conditionally Required - If response is not successful and if error code available. + +- Tag: connect_rpc-tech-specific + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + diff --git a/crates/weaver_forge/expected_output/test/registry.md b/crates/weaver_forge/expected_output/test/registry.md index e26e8cc5..a57ae63f 100644 --- a/crates/weaver_forge/expected_output/test/registry.md +++ b/crates/weaver_forge/expected_output/test/registry.md @@ -4,18 +4,26 @@ Url: # Attribute Groups +- [registry.exception](attribute_group/registry_exception.md) - [attributes.jvm.memory](attribute_group/attributes_jvm_memory.md) +- [registry.client](attribute_group/registry_client.md) - [registry.db](attribute_group/registry_db.md) +- [registry.gen_ai](attribute_group/registry_gen_ai.md) - [registry.http](attribute_group/registry_http.md) - [registry.network](attribute_group/registry_network.md) +- [registry.rpc](attribute_group/registry_rpc.md) - [server](attribute_group/server.md) - [registry.url](attribute_group/registry_url.md) - [registry.user_agent](attribute_group/registry_user_agent.md) # Events -- [ios.lifecycle.events](event/ios_lifecycle_events.md) -- [android.lifecycle.events](event/android_lifecycle_events.md) +- [device.app.lifecycle](event/device_app_lifecycle.md) +- [trace-exception](event/trace_exception.md) +- [feature_flag](event/feature_flag.md) +- [gen_ai.content.prompt](event/gen_ai_content_prompt.md) +- [gen_ai.content.completion](event/gen_ai_content_completion.md) +- [rpc.message](event/rpc_message.md) # Metrics @@ -55,4 +63,11 @@ Url: - [db.elasticsearch](span/db_elasticsearch.md) - [db.sql](span/db_sql.md) - [db.cosmosdb](span/db_cosmosdb.md) -- [db.tech](span/db_tech.md) \ No newline at end of file +- [db.tech](span/db_tech.md) +- [trace.gen_ai.client](span/trace_gen_ai_client.md) +- [rpc](span/rpc.md) +- [rpc.client](span/rpc_client.md) +- [rpc.server](span/rpc_server.md) +- [rpc.grpc](span/rpc_grpc.md) +- [rpc.jsonrpc](span/rpc_jsonrpc.md) +- [rpc.connect_rpc](span/rpc_connect_rpc.md) \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/rpc.md b/crates/weaver_forge/expected_output/test/span/rpc.md new file mode 100644 index 00000000..f9350121 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/rpc.md @@ -0,0 +1,136 @@ +## Group `rpc` (span) + +### Brief + +This document defines semantic conventions for remote procedure calls. + + + +Prefix: rpc +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/rpc_client.md b/crates/weaver_forge/expected_output/test/span/rpc_client.md new file mode 100644 index 00000000..8a59d1e4 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/rpc_client.md @@ -0,0 +1,167 @@ +## Group `rpc.client` (span) + +### Brief + +This document defines semantic conventions for remote procedure call client spans. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/rpc_connect_rpc.md b/crates/weaver_forge/expected_output/test/span/rpc_connect_rpc.md new file mode 100644 index 00000000..68dedd1b --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/rpc_connect_rpc.md @@ -0,0 +1,190 @@ +## Group `rpc.connect_rpc` (span) + +### Brief + +Tech-specific attributes for Connect RPC. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Conditionally Required - If response is not successful and if error code available. + +- Tag: connect_rpc-tech-specific + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/rpc_grpc.md b/crates/weaver_forge/expected_output/test/span/rpc_grpc.md new file mode 100644 index 00000000..215eb446 --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/rpc_grpc.md @@ -0,0 +1,190 @@ +## Group `rpc.grpc` (span) + +### Brief + +Tech-specific attributes for gRPC. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Required + +- Tag: grpc-tech-specific + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/rpc_jsonrpc.md b/crates/weaver_forge/expected_output/test/span/rpc_jsonrpc.md new file mode 100644 index 00000000..79507e9e --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/rpc_jsonrpc.md @@ -0,0 +1,212 @@ +## Group `rpc.jsonrpc` (span) + +### Brief + +Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/). + + + +Prefix: rpc.jsonrpc +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Conditionally Required - If response is not successful. + +- Tag: jsonrpc-tech-specific + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Conditionally Required - If other than the default version (`1.0`) + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is always required for jsonrpc. See the note in the general RPC conventions for more information. + +- Requirement Level: Required + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/rpc_server.md b/crates/weaver_forge/expected_output/test/span/rpc_server.md new file mode 100644 index 00000000..4aa8da9a --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/rpc_server.md @@ -0,0 +1,203 @@ +## Group `rpc.server` (span) + +### Brief + +Semantic Convention for RPC server spans + + + +Prefix: +Kind: server + +### Attributes + + +#### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/span/trace_gen_ai_client.md b/crates/weaver_forge/expected_output/test/span/trace_gen_ai_client.md new file mode 100644 index 00000000..a39e115b --- /dev/null +++ b/crates/weaver_forge/expected_output/test/span/trace_gen_ai_client.md @@ -0,0 +1,251 @@ +## Group `trace.gen_ai.client` (span) + +### Brief + +Describes GenAI operation span. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `gen_ai.request.max_tokens` + +The maximum number of tokens the model generates for a request. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.temperature` + +The temperature setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_p` + +The top_p sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Tag: llm-generic-request + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_k` + +The top_k sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.stop_sequences` + +List of sequences that the model will use to stop generating further tokens. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "forest", + "lived", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.frequency_penalty` + +The frequency penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.presence_penalty` + +The presence penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.id` + +The unique identifier for the completion. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.finish_reasons` + +Array of reasons the model stopped generating tokens, corresponding to each generation received. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.input_tokens` + +The number of tokens used in the GenAI input (prompt). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.output_tokens` + +The number of tokens used in the GenAI response (completion). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +- Requirement Level: Required + +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai + +- Stability: Experimental + + +#### Attribute `gen_ai.request.model` + +The name of the GenAI model a request is being made to. + + +The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Required + +- Type: string +- Examples: gpt-4 + +- Stability: Experimental + + +#### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Required + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.model` + +The name of the model that generated the response. + + +If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/test/spans.md b/crates/weaver_forge/expected_output/test/spans.md index 38c6cdb2..63012f12 100644 --- a/crates/weaver_forge/expected_output/test/spans.md +++ b/crates/weaver_forge/expected_output/test/spans.md @@ -3672,4 +3672,1360 @@ The user-agent value is generated by SDK which is a combination of
`sdk_vers - Stability: Stable + +## Group `trace.gen_ai.client` (span) + +### Brief + +Describes GenAI operation span. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `gen_ai.request.max_tokens` + +The maximum number of tokens the model generates for a request. + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.temperature` + +The temperature setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_p` + +The top_p sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Tag: llm-generic-request + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.top_k` + +The top_k sampling setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 1.0, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.stop_sequences` + +List of sequences that the model will use to stop generating further tokens. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "forest", + "lived", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.frequency_penalty` + +The frequency penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.request.presence_penalty` + +The presence penalty setting for the GenAI request. + + +- Requirement Level: Recommended + +- Type: double +- Examples: [ + 0.1, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.id` + +The unique identifier for the completion. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "chatcmpl-123", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.finish_reasons` + +Array of reasons the model stopped generating tokens, corresponding to each generation received. + + +- Requirement Level: Recommended + +- Type: string[] +- Examples: [ + "stop", +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.input_tokens` + +The number of tokens used in the GenAI input (prompt). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 100, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.usage.output_tokens` + +The number of tokens used in the GenAI response (completion). + + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 180, +] + +- Stability: Experimental + + +#### Attribute `gen_ai.system` + +The Generative AI product as identified by the client or server instrumentation. + + +The `gen_ai.system` describes a family of GenAI models with specific model identified +by `gen_ai.request.model` and `gen_ai.response.model` attributes. + +The actual GenAI product may differ from the one identified by the client. +For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` +is set to `openai` based on the instrumentation's best knowledge. + +For custom model, a custom friendly name SHOULD be used. +If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + +- Requirement Level: Required + +- Type: Enum [openai, vertex_ai, anthropic, cohere] +- Examples: openai + +- Stability: Experimental + + +#### Attribute `gen_ai.request.model` + +The name of the GenAI model a request is being made to. + + +The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Required + +- Type: string +- Examples: gpt-4 + +- Stability: Experimental + + +#### Attribute `gen_ai.operation.name` + +The name of the operation being performed. + + +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. + +- Requirement Level: Required + +- Type: Enum [chat, text_completion] + +- Stability: Experimental + + +#### Attribute `gen_ai.response.model` + +The name of the model that generated the response. + + +If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "gpt-4-0613", +] + +- Stability: Experimental + + + +## Group `rpc` (span) + +### Brief + +This document defines semantic conventions for remote procedure calls. + + + +Prefix: rpc +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + + +## Group `rpc.client` (span) + +### Brief + +This document defines semantic conventions for remote procedure call client spans. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Group `rpc.server` (span) + +### Brief + +Semantic Convention for RPC server spans + + + +Prefix: +Kind: server + +### Attributes + + +#### Attribute `client.address` + +Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. + + +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. + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "client.example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `client.port` + +Client port number. + + +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. + +- Requirement Level: Recommended + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + +#### Attribute `network.peer.address` + +Peer address of the network connection - IP address or Unix domain socket name. + + +- Requirement Level: Recommended + +- Type: string +- Examples: [ + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `network.peer.port` + +Peer port number of the network connection. + + +- Requirement Level: Optional + +- Type: int +- Examples: [ + 65123, +] + +- Stability: Stable + + + +## Group `rpc.grpc` (span) + +### Brief + +Tech-specific attributes for gRPC. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.grpc.request.metadata` + +gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.response.metadata` + +gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: grpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.grpc.status_code` + +The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. + + +- Requirement Level: Required + +- Tag: grpc-tech-specific + +- Type: Enum [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] + +- Stability: Experimental + + + +## Group `rpc.jsonrpc` (span) + +### Brief + +Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/). + + + +Prefix: rpc.jsonrpc +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.jsonrpc.error_code` + +`error.code` property of response if it is an error response. + + +- Requirement Level: Conditionally Required - If response is not successful. + +- Tag: jsonrpc-tech-specific + +- Type: int +- Examples: [ + -32700, + 100, +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.error_message` + +`error.message` property of response if it is an error response. + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "Parse error", + "User already exists", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.request_id` + +`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. + + + +- Requirement Level: Recommended + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "10", + "request-7", + "", +] + +- Stability: Experimental + + +#### Attribute `rpc.jsonrpc.version` + +Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. + + +- Requirement Level: Conditionally Required - If other than the default version (`1.0`) + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: [ + "2.0", + "1.0", +] + +- Stability: Experimental + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is always required for jsonrpc. See the note in the general RPC conventions for more information. + +- Requirement Level: Required + +- Tag: jsonrpc-tech-specific + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + + +## Group `rpc.connect_rpc` (span) + +### Brief + +Tech-specific attributes for Connect RPC. + + + +Prefix: +Kind: none + +### Attributes + + +#### Attribute `network.transport` + +[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + + + +The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +- Requirement Level: Recommended + +- Type: Enum [tcp, udp, pipe, unix] +- Examples: [ + "tcp", + "udp", +] + +- Stability: Stable + + +#### Attribute `network.type` + +[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. + + +The value SHOULD be normalized to lowercase. + +- Requirement Level: Recommended + +- Type: Enum [ipv4, ipv6] +- Examples: [ + "ipv4", + "ipv6", +] + +- Stability: Stable + + +#### Attribute `rpc.method` + +The name of the (logical) method being called, must be equal to the $method part in the span name. + + +This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: exampleMethod + +- Stability: Experimental + + +#### Attribute `rpc.service` + +The full (logical) name of the service being called, including its package name, if applicable. + + +This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +- Requirement Level: Recommended + +- Type: string +- Examples: myservice.EchoService + +- Stability: Experimental + + +#### Attribute `rpc.system` + +A string identifying the remoting system. See below for a list of well-known identifiers. + + +- Requirement Level: Required + +- Type: Enum [grpc, java_rmi, dotnet_wcf, apache_dubbo, connect_rpc] + +- Stability: Experimental + + +#### Attribute `server.address` + +RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + + + +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. + +- Requirement Level: Required + +- Type: string +- Examples: [ + "example.com", + "10.1.2.80", + "/tmp/my.sock", +] + +- Stability: Stable + + +#### Attribute `server.port` + +Server port number. + + +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. + +- Requirement Level: Conditionally Required - if the port is supported by the network transport used for communication. + +- Type: int +- Examples: [ + 80, + 8080, + 443, +] + +- Stability: Stable + + +#### Attribute `rpc.connect_rpc.error_code` + +The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. + + +- Requirement Level: Conditionally Required - If response is not successful and if error code available. + +- Tag: connect_rpc-tech-specific + +- Type: Enum [cancelled, unknown, invalid_argument, deadline_exceeded, not_found, already_exists, permission_denied, resource_exhausted, failed_precondition, aborted, out_of_range, unimplemented, internal, unavailable, data_loss, unauthenticated] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.request.metadata` + +Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]", +] + +- Stability: Experimental + + +#### Attribute `rpc.connect_rpc.response.metadata` + +Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + + + +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. + +- Requirement Level: Optional + +- Tag: connect_rpc-tech-specific + +- Type: template[string[]] +- Examples: [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]", +] + +- Stability: Experimental + + \ No newline at end of file diff --git a/crates/weaver_forge/expected_output/whitespace_control/registry.md b/crates/weaver_forge/expected_output/whitespace_control/registry.md index e2d11600..dde1138c 100644 --- a/crates/weaver_forge/expected_output/whitespace_control/registry.md +++ b/crates/weaver_forge/expected_output/whitespace_control/registry.md @@ -4,18 +4,26 @@ Url: ## Attribute Groups +- [registry.exception](attribute_group/registry_exception.md) - [attributes.jvm.memory](attribute_group/attributes_jvm_memory.md) +- [registry.client](attribute_group/registry_client.md) - [registry.db](attribute_group/registry_db.md) +- [registry.gen_ai](attribute_group/registry_gen_ai.md) - [registry.http](attribute_group/registry_http.md) - [registry.network](attribute_group/registry_network.md) +- [registry.rpc](attribute_group/registry_rpc.md) - [server](attribute_group/server.md) - [registry.url](attribute_group/registry_url.md) - [registry.user_agent](attribute_group/registry_user_agent.md) ## Events -- [ios.lifecycle.events](event/ios_lifecycle_events.md) -- [android.lifecycle.events](event/android_lifecycle_events.md) +- [device.app.lifecycle](event/device_app_lifecycle.md) +- [trace-exception](event/trace_exception.md) +- [feature_flag](event/feature_flag.md) +- [gen_ai.content.prompt](event/gen_ai_content_prompt.md) +- [gen_ai.content.completion](event/gen_ai_content_completion.md) +- [rpc.message](event/rpc_message.md) ## Metrics @@ -54,3 +62,10 @@ Url: - [db.sql](span/db_sql.md) - [db.cosmosdb](span/db_cosmosdb.md) - [db.tech](span/db_tech.md) +- [trace.gen_ai.client](span/trace_gen_ai_client.md) +- [rpc](span/rpc.md) +- [rpc.client](span/rpc_client.md) +- [rpc.server](span/rpc_server.md) +- [rpc.grpc](span/rpc_grpc.md) +- [rpc.jsonrpc](span/rpc_jsonrpc.md) +- [rpc.connect_rpc](span/rpc_connect_rpc.md) diff --git a/crates/weaver_forge/overloaded-templates/test/group.md b/crates/weaver_forge/overloaded-templates/test/group.md index a817d676..cd813631 100644 --- a/crates/weaver_forge/overloaded-templates/test/group.md +++ b/crates/weaver_forge/overloaded-templates/test/group.md @@ -7,7 +7,25 @@ {{ ctx.brief | trim }} +{% if ctx.prefix %} prefix: {{ ctx.prefix }} +{% endif %} +{% if ctx.type == "event" %} +## Event details + +The event name MUST be `{% ctx.id %} + +{% if ctx.body %} +## Body Fields + +{% for bodyField in ctx.body.fields %} +### Field `{{ bodyField.id }}` +{% endfor %} +{% else %} +No event body defined. +{% endif %} + +{% endif %} ## Attributes diff --git a/crates/weaver_forge/src/file_loader.rs b/crates/weaver_forge/src/file_loader.rs index b9485426..c6ff82a0 100644 --- a/crates/weaver_forge/src/file_loader.rs +++ b/crates/weaver_forge/src/file_loader.rs @@ -286,9 +286,14 @@ mod tests { // Test all files let embedded_files: HashSet = embedded_loader.all_files().into_iter().collect(); - assert_eq!(embedded_files.len(), 17); + assert_eq!( + embedded_files.len(), + 18, + "Embedded files: {:?}", + embedded_files + ); let fs_files: HashSet = fs_loader.all_files().into_iter().collect(); - assert_eq!(fs_files.len(), 17); + assert_eq!(fs_files.len(), 18, "FS files: {:?}", fs_files); // Test that the files are the same between the embedded and file system loaders assert_eq!(embedded_files, fs_files); // Test that all the files can be loaded from the embedded loader diff --git a/crates/weaver_forge/src/registry.rs b/crates/weaver_forge/src/registry.rs index 07cc629d..9e757e02 100644 --- a/crates/weaver_forge/src/registry.rs +++ b/crates/weaver_forge/src/registry.rs @@ -8,6 +8,7 @@ use crate::error::Error; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; use weaver_resolved_schema::attribute::Attribute; +use weaver_resolved_schema::body::Body; use weaver_resolved_schema::catalog::Catalog; use weaver_resolved_schema::lineage::GroupLineage; use weaver_resolved_schema::registry::{Constraint, Group, Registry}; @@ -104,6 +105,9 @@ pub struct ResolvedGroup { /// The readable name for attribute groups used when generating registry tables. #[serde(skip_serializing_if = "Option::is_none")] pub display_name: Option, + /// The body specification used for event semantic conventions. + #[serde(skip_serializing_if = "Option::is_none")] + pub body: Option, } impl ResolvedGroup { @@ -134,6 +138,12 @@ impl ResolvedGroup { }) .collect(); let lineage = group.lineage.clone(); + let body = if group_type == GroupType::Event { + group.body.clone() + } else { + None + }; + if !errors.is_empty() { return Err(Error::CompoundError(errors)); } @@ -156,6 +166,7 @@ impl ResolvedGroup { name: group.name.clone(), lineage, display_name: group.display_name.clone(), + body, }) } } @@ -196,6 +207,12 @@ impl ResolvedRegistry { }) .collect(); let lineage = group.lineage.clone(); + let body = if group_type == GroupType::Event { + group.body.clone() + } else { + None + }; + ResolvedGroup { id, r#type: group_type, @@ -215,6 +232,7 @@ impl ResolvedRegistry { name: group.name.clone(), lineage, display_name: group.display_name.clone(), + body, } }) .collect(); diff --git a/crates/weaver_forge/templates/test/body.j2 b/crates/weaver_forge/templates/test/body.j2 new file mode 100644 index 00000000..7bb8b869 --- /dev/null +++ b/crates/weaver_forge/templates/test/body.j2 @@ -0,0 +1,52 @@ +{%- if group.type == "event" -%} +### Body Fields + +{% if group.body -%} +{% for bodyField in group.body.fields -%} +#### Field `{{ bodyField.name }}` + +{{ bodyField.brief }} + +{%- if bodyField.note %} +{{ bodyField.note | trim }} +{% endif %} + +{%- if bodyField.requirement_level == "required" %} +- Requirement Level: Required +{%- elif bodyField.requirement_level.conditionally_required %} +- Requirement Level: Conditionally Required - {{ bodyField.requirement_level.conditionally_required }} +{%- elif bodyField.requirement_level == "recommended" %} +- Requirement Level: Recommended +{%- else %} +- Requirement Level: Optional +{%- endif %} + +{%- if bodyField.type is mapping %} +- Type: Enum [{{ bodyField.type.members | map(attribute="value") | join(", ") | trim }}] +{%- else %} +- Type: {{ bodyField.type }} +{%- endif %} + +{%- if bodyField.examples %} +{%- if bodyField.examples is sequence %} +- Examples: {{ bodyField.examples | pprint }} +{%- else %} +- Examples: {{ bodyField.examples }} +{%- endif %} +{%- endif %} + +{%- if bodyField.deprecated %} +- Deprecated: {{ bodyField.deprecated }} +{%- endif %} + +{%- if bodyField.stability %} +- Stability: {{ bodyField.stability | capitalize }} +{%- endif %} + +{% endfor -%} +{%- else -%} + +No event body defined. + +{% endif %} +{%- endif -%} \ No newline at end of file diff --git a/crates/weaver_forge/templates/test/event.md b/crates/weaver_forge/templates/test/event.md index 43736aa7..e3f9a2c3 100644 --- a/crates/weaver_forge/templates/test/event.md +++ b/crates/weaver_forge/templates/test/event.md @@ -10,6 +10,57 @@ Prefix: {{ ctx.prefix }} Name: {{ ctx.name }} +### Body Fields + +{% if ctx.body -%} +{% for bodyField in ctx.body.fields -%} +#### Field `{{ bodyField.name }}` + +{{ bodyField.brief }} + +{%- if bodyField.note %} +{{ bodyField.note | trim }} +{% endif %} + +{%- if bodyField.requirement_level == "required" %} +- Requirement Level: Required +{%- elif bodyField.requirement_level.conditionally_required %} +- Requirement Level: Conditionally Required - {{ bodyField.requirement_level.conditionally_required }} +{%- elif bodyField.requirement_level == "recommended" %} +- Requirement Level: Recommended +{%- else %} +- Requirement Level: Optional +{%- endif %} + +{%- if bodyField.type is mapping %} +- Type: Enum [{{ bodyField.type.members | map(attribute="value") | join(", ") | trim }}] +{%- else %} +- Type: {{ bodyField.type }} +{%- endif %} + +{%- if bodyField.examples %} +{%- if bodyField.examples is sequence %} +- Examples: {{ bodyField.examples | pprint }} +{%- else %} +- Examples: {{ bodyField.examples }} +{%- endif %} +{%- endif %} + +{%- if bodyField.deprecated %} +- Deprecated: {{ bodyField.deprecated }} +{%- endif %} + +{%- if bodyField.stability %} +- Stability: {{ bodyField.stability | capitalize }} +{%- endif %} + +{% endfor -%} +{%- else -%} + +No event body defined. + +{%- endif -%} + ## Attributes {% for attribute in ctx.attributes %} diff --git a/crates/weaver_forge/templates/test/events.md b/crates/weaver_forge/templates/test/events.md index eae78bc1..8ddad693 100644 --- a/crates/weaver_forge/templates/test/events.md +++ b/crates/weaver_forge/templates/test/events.md @@ -10,6 +10,10 @@ Prefix: {{ group.prefix }} Name: {{ group.name }} +{% if group.type == "event" -%} +{% include "body.j2" -%} +{% endif -%} + ### Attributes {% for attribute in group.attributes %} diff --git a/crates/weaver_forge/templates/test/group.md b/crates/weaver_forge/templates/test/group.md index 1d14bc87..db77f81c 100644 --- a/crates/weaver_forge/templates/test/group.md +++ b/crates/weaver_forge/templates/test/group.md @@ -9,6 +9,11 @@ prefix: {{ ctx.prefix }} +{% if ctx.type == "event" -%} +{%- set group = ctx -%} +{% include "body.j2" -%} +{% endif -%} + ## Attributes {% for attribute in ctx.attributes %} diff --git a/crates/weaver_forge/templates/test/groups.md b/crates/weaver_forge/templates/test/groups.md index 8b072179..8b1f29fc 100644 --- a/crates/weaver_forge/templates/test/groups.md +++ b/crates/weaver_forge/templates/test/groups.md @@ -9,6 +9,10 @@ prefix: {{ group.prefix }} +{% if group.type == "event" -%} +{% include "body.j2" -%} +{% endif -%} + ### Attributes {% for attribute in group.attributes %} diff --git a/crates/weaver_resolved_schema/src/attribute.rs b/crates/weaver_resolved_schema/src/attribute.rs index 8326a9c1..42b75c35 100644 --- a/crates/weaver_resolved_schema/src/attribute.rs +++ b/crates/weaver_resolved_schema/src/attribute.rs @@ -91,7 +91,7 @@ pub struct UnresolvedAttribute { /// An internal reference to an attribute in the catalog. #[derive( - Serialize, Deserialize, Debug, Copy, Clone, Eq, PartialEq, PartialOrd, Ord, JsonSchema, + Serialize, Deserialize, Debug, Copy, Clone, Eq, PartialEq, Hash, PartialOrd, Ord, JsonSchema, )] pub struct AttributeRef(pub u32); diff --git a/crates/weaver_resolved_schema/src/body.rs b/crates/weaver_resolved_schema/src/body.rs new file mode 100644 index 00000000..7ab458cc --- /dev/null +++ b/crates/weaver_resolved_schema/src/body.rs @@ -0,0 +1,90 @@ +// SPDX-License-Identifier: Apache-2.0 + +#![allow(rustdoc::invalid_html_tags)] + +//! Specification of a resolved body field. + +use crate::attribute::AttributeRef; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use weaver_semconv::attribute::{AttributeType, Examples, RequirementLevel}; +use weaver_semconv::body::{BodyFieldSpec, BodySpec}; +use weaver_semconv::stability::Stability; + +/// An attribute definition. +#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq, Hash, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct Body { + /// The body specification. + #[serde(skip_serializing_if = "Option::is_none")] + pub fields: Option>, + // Not yet defined in the spec or implemented in the resolver + // The body value when there are no fields + // #[serde(skip_serializing_if = "Option::is_none")] + // pub value: Option +} + +/// An attribute definition. +#[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq, Hash, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct BodyField { + /// Attribute name. + pub name: String, + /// A reference to an attribute definition, used to populate the relevant + /// fields of the body field, unless they are overridden by the body field. + #[serde(skip_serializing_if = "Option::is_none")] + pub r#attr: Option, + /// A alias to use for the field for the referenced attribute. + #[serde(skip_serializing_if = "Option::is_none")] + pub alias: Option, + /// Either a string literal denoting the type as a primitive or an + /// array type, a template type or an enum definition. + pub r#type: AttributeType, + /// A brief description of the attribute. + #[serde(skip_serializing_if = "String::is_empty")] + pub brief: String, + /// Sequence of example values for the attribute or single example + /// value. They are required only for string and string array + /// attributes. Example values must be of the same type of the + /// attribute. If only a single example is provided, it can directly + /// be reported without encapsulating it into a sequence/dictionary. + #[serde(skip_serializing_if = "Option::is_none")] + pub examples: Option, + /// Specifies if the attribute is mandatory. Can be "required", + /// "conditionally_required", "recommended" or "opt_in". When omitted, + /// the attribute is "recommended". When set to + /// "conditionally_required", the string provided as MUST + /// specify the conditions under which the attribute is required. + pub requirement_level: RequirementLevel, + /// A more elaborate description of the attribute. + /// It defaults to an empty string. + #[serde(skip_serializing_if = "String::is_empty")] + #[serde(default)] + pub note: String, + /// Specifies the stability of the attribute. + /// Note that, if stability is missing but deprecated is present, it will + /// automatically set the stability to deprecated. If deprecated is + /// present and stability differs from deprecated, this will result in an + /// error. + #[serde(skip_serializing_if = "Option::is_none")] + pub stability: Option, + /// Specifies if the attribute is deprecated. The string + /// provided as MUST specify why it's deprecated and/or what + /// to use instead. See also stability. + #[serde(skip_serializing_if = "Option::is_none")] + pub deprecated: Option, +} + +/// An unresolved body definition. +#[derive(Debug, Deserialize, Clone)] +pub struct UnresolvedBody { + /// The body specification. + pub spec: BodySpec, +} + +/// An unresolved body field definition. +#[derive(Debug, Deserialize, Clone)] +pub struct UnresolvedBodyField { + /// The body field specification. + pub spec: BodyFieldSpec, +} diff --git a/crates/weaver_resolved_schema/src/error.rs b/crates/weaver_resolved_schema/src/error.rs index f38f43ff..1d5154ab 100644 --- a/crates/weaver_resolved_schema/src/error.rs +++ b/crates/weaver_resolved_schema/src/error.rs @@ -2,11 +2,13 @@ //! Error types and utilities. +use serde::Deserialize; + use crate::attribute::AttributeRef; -use crate::error::Error::{AttributeNotFound, CompoundError}; +use crate::error::Error::{AttributeNotFound, CompoundError, NotImplemented}; /// Errors emitted by this crate. -#[derive(thiserror::Error, Debug, Clone)] +#[derive(thiserror::Error, Debug, Clone, Deserialize)] pub enum Error { /// Attribute reference not found in the catalog. #[error("Attribute reference {attr_ref} (group: {group_id}) not found in the catalog")] @@ -20,6 +22,13 @@ pub enum Error { /// A generic container for multiple errors. #[error("Errors:\n{0:#?}")] CompoundError(Vec), + + /// A generic error identifying a feature that has not yet been implemented. + #[error("Not Implemented: {message}")] + NotImplemented { + /// A message describing the feature that has not been implemented. + message: String, + }, } /// Handles a list of errors and returns a compound error if the list is not @@ -35,6 +44,7 @@ pub fn handle_errors(errors: Vec) -> Result<(), Error> { impl Error { /// Creates a compound error from a list of errors. /// Note: All compound errors are flattened. + #[must_use] pub fn compound_error(errors: Vec) -> Self { CompoundError( errors @@ -42,6 +52,7 @@ impl Error { .flat_map(|e| match e { CompoundError(errors) => errors, e @ AttributeNotFound { .. } => vec![e], + e @ NotImplemented { .. } => vec![e], }) .collect(), ) diff --git a/crates/weaver_resolved_schema/src/lib.rs b/crates/weaver_resolved_schema/src/lib.rs index 61ed0ed7..d88d872e 100644 --- a/crates/weaver_resolved_schema/src/lib.rs +++ b/crates/weaver_resolved_schema/src/lib.rs @@ -14,8 +14,9 @@ use std::collections::HashMap; use weaver_version::Versions; pub mod attribute; +pub mod body; pub mod catalog; -mod error; +pub mod error; pub mod instrumentation_library; pub mod lineage; pub mod metric; diff --git a/crates/weaver_resolved_schema/src/registry.rs b/crates/weaver_resolved_schema/src/registry.rs index c41fc405..604c1c90 100644 --- a/crates/weaver_resolved_schema/src/registry.rs +++ b/crates/weaver_resolved_schema/src/registry.rs @@ -13,6 +13,7 @@ use weaver_semconv::group::{GroupType, InstrumentSpec, SpanKindSpec}; use weaver_semconv::stability::Stability; use crate::attribute::{Attribute, AttributeRef}; +use crate::body::Body; use crate::catalog::Catalog; use crate::error::{handle_errors, Error}; use crate::lineage::GroupLineage; @@ -126,6 +127,10 @@ pub struct Group { /// The readable name for attribute groups used when generating registry tables. #[serde(skip_serializing_if = "Option::is_none")] pub display_name: Option, + /// The body of the event. + /// This fields is only used for event groups. + #[serde(skip_serializing_if = "Option::is_none")] + pub body: Option, } /// Common statistics for a group. diff --git a/crates/weaver_resolved_schema/src/signal.rs b/crates/weaver_resolved_schema/src/signal.rs index a702191c..a5f88c90 100644 --- a/crates/weaver_resolved_schema/src/signal.rs +++ b/crates/weaver_resolved_schema/src/signal.rs @@ -6,6 +6,7 @@ use schemars::JsonSchema; use serde::{Deserialize, Serialize}; use crate::attribute::AttributeRef; +use crate::body::Body; use crate::metric::MetricRef; use crate::tags::Tags; @@ -44,17 +45,15 @@ pub struct MultivariateMetric { tags: Option, } -/// An event signal. +/// An event specification, used for both Span and Log events. #[derive(Serialize, Deserialize, Debug, JsonSchema)] #[serde(deny_unknown_fields)] pub struct Event { /// The name of the event. - name: String, + event_name: String, /// References to attributes defined in the catalog. #[serde(skip_serializing_if = "Vec::is_empty")] attributes: Vec, - /// The domain of the event. - domain: String, /// Brief description of the event. brief: Option, /// Longer description. @@ -63,6 +62,9 @@ pub struct Event { /// A set of tags for the event. #[serde(skip_serializing_if = "Option::is_none")] tags: Option, + /// The body of the event, not used for Span events. + #[serde(skip_serializing_if = "Option::is_none")] + body: Option, } /// A span signal. @@ -79,7 +81,7 @@ pub struct Span { kind: Option, /// The events of the span. #[serde(skip_serializing_if = "Vec::is_empty")] - events: Vec, + events: Vec, /// The links of the span. #[serde(skip_serializing_if = "Vec::is_empty")] links: Vec, @@ -108,25 +110,6 @@ pub enum SpanKind { Consumer, } -/// A span event specification. -#[derive(Serialize, Deserialize, Debug, JsonSchema)] -#[serde(deny_unknown_fields)] -pub struct SpanEvent { - /// The name of the span event. - pub event_name: String, - /// The attributes of the span event. - #[serde(skip_serializing_if = "Vec::is_empty")] - pub attributes: Vec, - /// Brief description of the span event. - pub brief: Option, - /// Longer description. - /// It defaults to an empty string. - pub note: Option, - /// A set of tags for the span event. - #[serde(skip_serializing_if = "Option::is_none")] - pub tags: Option, -} - /// A span link specification. #[derive(Serialize, Deserialize, Debug, JsonSchema)] #[serde(deny_unknown_fields)] diff --git a/crates/weaver_resolver/data/registry-test-4-events/expected-attribute-catalog.json b/crates/weaver_resolver/data/registry-test-4-events/expected-attribute-catalog.json index dcd9d812..2b329bad 100644 --- a/crates/weaver_resolver/data/registry-test-4-events/expected-attribute-catalog.json +++ b/crates/weaver_resolver/data/registry-test-4-events/expected-attribute-catalog.json @@ -1,73 +1,1402 @@ [ { - "name": "ios.state", + "name": "browser.brands", + "type": "string[]", + "brief": "Array of brand name and version separated by a space", + "examples": [ + " Not A;Brand 99", + "Chromium 99", + "Chrome 99" + ], + "requirement_level": "recommended", + "note": "This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).\n" + }, + { + "name": "browser.platform", + "type": "string", + "brief": "The platform on which the browser is running", + "examples": [ + "Windows", + "macOS", + "Android" + ], + "requirement_level": "recommended", + "note": "This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides.\n" + }, + { + "name": "browser.mobile", + "type": "boolean", + "brief": "A boolean that is true if the browser is running on a mobile device", + "requirement_level": "recommended", + "note": "This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset.\n" + }, + { + "name": "browser.language", + "type": "string", + "brief": "Preferred language of the user using the browser", + "examples": [ + "en", + "en-US", + "fr", + "fr-FR" + ], + "requirement_level": "recommended", + "note": "This value is intended to be taken from the Navigator API `navigator.language`.\n" + }, + { + "name": "client.name", + "type": "string", + "brief": "The name of the client that reported the exception.\n", + "examples": [ + "myclient" + ], + "requirement_level": "recommended" + }, + { + "name": "browser.platform", + "type": "string", + "brief": "The browser platform", + "examples": [ + "Windows", + "macOS", + "Android" + ], + "requirement_level": "recommended", + "note": "Test value.", + "stability": "stable" + }, + { + "name": "http.url", + "type": "string", + "brief": "The Url", + "examples": [ + "https://example.com" + ], + "requirement_level": "recommended", + "note": "Test url value.", + "stability": "stable" + }, + { + "name": "log.event.attr", + "type": "string", + "brief": "Just making sure the referenced attributes are defined", + "examples": "some value", + "requirement_level": "recommended", + "note": "Test value.", + "stability": "stable" + }, + { + "name": "session.id", + "type": "string", + "brief": "The session id", + "examples": "127836abcdef98", + "requirement_level": "recommended", + "note": "Test value.", + "stability": "stable" + }, + { + "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.\n", + "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.\n", + "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.\n", + "examples": [ + "java.net.ConnectException", + "OSError" + ], + "requirement_level": "recommended", + "stability": "stable" + }, + { + "name": "exception.message", + "type": "string", + "brief": "The exception message.", + "examples": [ + "Division by zero", + "Can't convert 'int' object to str implicitly" + ], + "requirement_level": "recommended", + "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.\n", + "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.escaped", + "type": "boolean", + "brief": "SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span.\n", + "requirement_level": "recommended", + "note": "An exception is considered to have escaped (or left) the scope of a span,\nif that span is ended while the exception is still logically \"in flight\".\nThis may be actually \"in flight\" in some languages (e.g. if the exception\nis passed to a Context manager's `__exit__` method in Python) but will\nusually be caught at the point of recording the exception in most languages.\n\nIt is usually not possible to determine at the point where an exception is thrown\nwhether it will escape the scope of a span.\nHowever, it is trivial to know that an exception\nwill escape, if one checks for an active exception just before ending the span,\nas done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception).\n\nIt follows that an exception may still escape the scope of the span\neven if the `exception.escaped` attribute was not set or set to false,\nsince the event might have been recorded at a time where it was not\nclear whether the exception will escape.", + "stability": "stable" + }, + { + "name": "gen_ai.system", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "openai", + "value": "openai", + "brief": "OpenAI", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "vertex_ai", + "value": "vertex_ai", + "brief": "Vertex AI", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "anthropic", + "value": "anthropic", + "brief": "Anthropic", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cohere", + "value": "cohere", + "brief": "Cohere", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The Generative AI product as identified by the client or server instrumentation.", + "examples": "openai", + "requirement_level": "recommended", + "note": "The `gen_ai.system` describes a family of GenAI models with specific model identified\nby `gen_ai.request.model` and `gen_ai.response.model` attributes.\n\nThe actual GenAI product may differ from the one identified by the client.\nFor example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system`\nis set to `openai` based on the instrumentation's best knowledge.\n\nFor custom model, a custom friendly name SHOULD be used.\nIf none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.\n", + "stability": "experimental" + }, + { + "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": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.max_tokens", + "type": "int", + "brief": "The maximum number of tokens the model generates for a request.", + "examples": [ + 100 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.temperature", + "type": "double", + "brief": "The temperature setting for the GenAI request.", + "examples": [ + 0.0 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.top_p", + "type": "double", + "brief": "The top_p sampling setting for the GenAI request.", + "examples": [ + 1.0 + ], + "tag": "llm-generic-request", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.top_k", + "type": "double", + "brief": "The top_k sampling setting for the GenAI request.", + "examples": [ + 1.0 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.stop_sequences", + "type": "string[]", + "brief": "List of sequences that the model will use to stop generating further tokens.", + "examples": [ + "forest", + "lived" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.frequency_penalty", + "type": "double", + "brief": "The frequency penalty setting for the GenAI request.", + "examples": [ + 0.1 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.request.presence_penalty", + "type": "double", + "brief": "The presence penalty setting for the GenAI request.", + "examples": [ + 0.1 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.response.id", + "type": "string", + "brief": "The unique identifier for the completion.", + "examples": [ + "chatcmpl-123" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "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": "experimental" + }, + { + "name": "gen_ai.response.finish_reasons", + "type": "string[]", + "brief": "Array of reasons the model stopped generating tokens, corresponding to each generation received.", + "examples": [ + "stop" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.usage.input_tokens", + "type": "int", + "brief": "The number of tokens used in the GenAI input (prompt).", + "examples": [ + 100 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.usage.output_tokens", + "type": "int", + "brief": "The number of tokens used in the GenAI response (completion).", + "examples": [ + 180 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.token.type", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "input", + "value": "input", + "brief": "Input tokens (prompt, input, etc.)", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "completion", + "value": "output", + "brief": "Output tokens (completion, response, etc.)", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The type of token being counted.", + "examples": [ + "input", + "output" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "gen_ai.prompt", + "type": "string", + "brief": "The full prompt sent to the GenAI model.", + "examples": [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]" + ], + "requirement_level": "recommended", + "note": "It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)", + "stability": "experimental" + }, + { + "name": "gen_ai.completion", + "type": "string", + "brief": "The full response received from the GenAI model.", + "examples": [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]" + ], + "requirement_level": "recommended", + "note": "It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)", + "stability": "experimental" + }, + { + "name": "gen_ai.operation.name", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "chat", + "value": "chat", + "brief": "Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "text_completion", + "value": "text_completion", + "brief": "Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The name of the operation being performed.", + "requirement_level": "recommended", + "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.\n", + "stability": "experimental" + }, + { + "name": "network.carrier.icc", + "type": "string", + "brief": "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network.", + "examples": "DE", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "network.carrier.mcc", + "type": "string", + "brief": "The mobile carrier country code.", + "examples": "310", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "network.carrier.mnc", + "type": "string", + "brief": "The mobile carrier network code.", + "examples": "001", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "network.carrier.name", + "type": "string", + "brief": "The name of the mobile carrier.", + "examples": "sprint", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "network.connection.subtype", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "gprs", + "value": "gprs", + "brief": "GPRS", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "edge", + "value": "edge", + "brief": "EDGE", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "umts", + "value": "umts", + "brief": "UMTS", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cdma", + "value": "cdma", + "brief": "CDMA", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "evdo_0", + "value": "evdo_0", + "brief": "EVDO Rel. 0", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "evdo_a", + "value": "evdo_a", + "brief": "EVDO Rev. A", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cdma2000_1xrtt", + "value": "cdma2000_1xrtt", + "brief": "CDMA2000 1XRTT", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "hsdpa", + "value": "hsdpa", + "brief": "HSDPA", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "hsupa", + "value": "hsupa", + "brief": "HSUPA", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "hspa", + "value": "hspa", + "brief": "HSPA", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "iden", + "value": "iden", + "brief": "IDEN", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "evdo_b", + "value": "evdo_b", + "brief": "EVDO Rev. B", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "lte", + "value": "lte", + "brief": "LTE", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "ehrpd", + "value": "ehrpd", + "brief": "EHRPD", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "hspap", + "value": "hspap", + "brief": "HSPAP", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "gsm", + "value": "gsm", + "brief": "GSM", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "td_scdma", + "value": "td_scdma", + "brief": "TD-SCDMA", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "iwlan", + "value": "iwlan", + "brief": "IWLAN", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "nr", + "value": "nr", + "brief": "5G NR (New Radio)", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "nrnsa", + "value": "nrnsa", + "brief": "5G NRNSA (New Radio Non-Standalone)", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "lte_ca", + "value": "lte_ca", + "brief": "LTE CA", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.", + "examples": "LTE", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "network.connection.type", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "wifi", + "value": "wifi", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "wired", + "value": "wired", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cell", + "value": "cell", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unavailable", + "value": "unavailable", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unknown", + "value": "unknown", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The internet connection type.", + "examples": "wifi", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "network.local.address", + "type": "string", + "brief": "Local address of the network connection - IP address or Unix domain socket name.", + "examples": [ + "10.1.2.80", + "/tmp/my.sock" + ], + "requirement_level": "recommended", + "stability": "stable" + }, + { + "name": "network.local.port", + "type": "int", + "brief": "Local port number of the network connection.", + "examples": [ + 65123 + ], + "requirement_level": "recommended", + "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", + "stability": "stable" + }, + { + "name": "network.peer.port", + "type": "int", + "brief": "Peer port number of the network connection.", + "examples": [ + 65123 + ], + "requirement_level": "recommended", + "stability": "stable" + }, + { + "name": "network.protocol.name", + "type": "string", + "brief": "[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.", + "examples": [ + "amqp", + "http", + "mqtt" + ], + "requirement_level": "recommended", + "note": "The value SHOULD be normalized to lowercase.", + "stability": "stable" + }, + { + "name": "network.protocol.version", + "type": "string", + "brief": "The actual version of the protocol used for network communication.", + "examples": [ + "1.1", + "2" + ], + "requirement_level": "recommended", + "note": "If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.\n", + "stability": "stable" + }, + { + "name": "network.transport", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "tcp", + "value": "tcp", + "brief": "TCP", + "note": null, + "stability": "stable", + "deprecated": null + }, + { + "id": "udp", + "value": "udp", + "brief": "UDP", + "note": null, + "stability": "stable", + "deprecated": null + }, + { + "id": "pipe", + "value": "pipe", + "brief": "Named or anonymous pipe.", + "note": null, + "stability": "stable", + "deprecated": null + }, + { + "id": "unix", + "value": "unix", + "brief": "Unix domain socket", + "note": null, + "stability": "stable", + "deprecated": null + } + ] + }, + "brief": "[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication).\n", + "examples": [ + "tcp", + "udp" + ], + "requirement_level": "recommended", + "note": "The value SHOULD be normalized to lowercase.\n\nConsider always setting the transport when setting a port number, since\na port number is ambiguous without knowing the transport. For example\ndifferent processes could be listening on TCP port 12345 and UDP port 12345.\n", + "stability": "stable" + }, + { + "name": "network.type", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "ipv4", + "value": "ipv4", + "brief": "IPv4", + "note": null, + "stability": "stable", + "deprecated": null + }, + { + "id": "ipv6", + "value": "ipv6", + "brief": "IPv6", + "note": null, + "stability": "stable", + "deprecated": null + } + ] + }, + "brief": "[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent.", + "examples": [ + "ipv4", + "ipv6" + ], + "requirement_level": "recommended", + "note": "The value SHOULD be normalized to lowercase.", + "stability": "stable" + }, + { + "name": "network.io.direction", + "type": { + "allow_custom_values": false, + "members": [ + { + "id": "transmit", + "value": "transmit", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "receive", + "value": "receive", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The network IO operation direction.", + "examples": [ + "transmit" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.connect_rpc.error_code", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "cancelled", + "value": "cancelled", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unknown", + "value": "unknown", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "invalid_argument", + "value": "invalid_argument", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "deadline_exceeded", + "value": "deadline_exceeded", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "not_found", + "value": "not_found", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "already_exists", + "value": "already_exists", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "permission_denied", + "value": "permission_denied", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "resource_exhausted", + "value": "resource_exhausted", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "failed_precondition", + "value": "failed_precondition", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "aborted", + "value": "aborted", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "out_of_range", + "value": "out_of_range", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unimplemented", + "value": "unimplemented", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "internal", + "value": "internal", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unavailable", + "value": "unavailable", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "data_loss", + "value": "data_loss", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unauthenticated", + "value": "unauthenticated", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values.", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.connect_rpc.request.metadata", + "type": "template[string[]]", + "brief": "Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]" + ], + "requirement_level": "recommended", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.connect_rpc.response.metadata", + "type": "template[string[]]", + "brief": "Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]" + ], + "requirement_level": "recommended", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.grpc.status_code", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "ok", + "value": 0, + "brief": "OK", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cancelled", + "value": 1, + "brief": "CANCELLED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unknown", + "value": 2, + "brief": "UNKNOWN", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "invalid_argument", + "value": 3, + "brief": "INVALID_ARGUMENT", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "deadline_exceeded", + "value": 4, + "brief": "DEADLINE_EXCEEDED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "not_found", + "value": 5, + "brief": "NOT_FOUND", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "already_exists", + "value": 6, + "brief": "ALREADY_EXISTS", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "permission_denied", + "value": 7, + "brief": "PERMISSION_DENIED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "resource_exhausted", + "value": 8, + "brief": "RESOURCE_EXHAUSTED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "failed_precondition", + "value": 9, + "brief": "FAILED_PRECONDITION", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "aborted", + "value": 10, + "brief": "ABORTED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "out_of_range", + "value": 11, + "brief": "OUT_OF_RANGE", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unimplemented", + "value": 12, + "brief": "UNIMPLEMENTED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "internal", + "value": 13, + "brief": "INTERNAL", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unavailable", + "value": 14, + "brief": "UNAVAILABLE", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "data_loss", + "value": 15, + "brief": "DATA_LOSS", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unauthenticated", + "value": 16, + "brief": "UNAUTHENTICATED", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request.", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.grpc.request.metadata", + "type": "template[string[]]", + "brief": "gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]" + ], + "requirement_level": "recommended", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.grpc.response.metadata", + "type": "template[string[]]", + "brief": "gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]" + ], + "requirement_level": "recommended", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.error_code", + "type": "int", + "brief": "`error.code` property of response if it is an error response.", + "examples": [ + -32700, + 100 + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.error_message", + "type": "string", + "brief": "`error.message` property of response if it is an error response.", + "examples": [ + "Parse error", + "User already exists" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.request_id", + "type": "string", + "brief": "`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification.\n", + "examples": [ + "10", + "request-7", + "" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.version", + "type": "string", + "brief": "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted.", + "examples": [ + "2.0", + "1.0" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.method", + "type": "string", + "brief": "The name of the (logical) method being called, must be equal to the $method part in the span name.", + "examples": "exampleMethod", + "requirement_level": "recommended", + "note": "This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).\n", + "stability": "experimental" + }, + { + "name": "rpc.service", + "type": "string", + "brief": "The full (logical) name of the service being called, including its package name, if applicable.", + "examples": "myservice.EchoService", + "requirement_level": "recommended", + "note": "This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).\n", + "stability": "experimental" + }, + { + "name": "rpc.system", "type": { - "allow_custom_values": false, + "allow_custom_values": true, "members": [ { - "id": "active", - "value": "active", - "brief": "The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.\n", - "note": null + "id": "grpc", + "value": "grpc", + "brief": "gRPC", + "note": null, + "stability": "experimental", + "deprecated": null }, { - "id": "inactive", - "value": "inactive", - "brief": "The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.\n", - "note": null + "id": "java_rmi", + "value": "java_rmi", + "brief": "Java RMI", + "note": null, + "stability": "experimental", + "deprecated": null }, { - "id": "background", - "value": "background", - "brief": "The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`.\n", - "note": null + "id": "dotnet_wcf", + "value": "dotnet_wcf", + "brief": ".NET WCF", + "note": null, + "stability": "experimental", + "deprecated": null }, { - "id": "foreground", - "value": "foreground", - "brief": "The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`.\n", - "note": null + "id": "apache_dubbo", + "value": "apache_dubbo", + "brief": "Apache Dubbo", + "note": null, + "stability": "experimental", + "deprecated": null }, { - "id": "terminate", - "value": "terminate", - "brief": "The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.\n", - "note": null + "id": "connect_rpc", + "value": "connect_rpc", + "brief": "Connect RPC", + "note": null, + "stability": "experimental", + "deprecated": null } ] }, - "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", - "requirement_level": "required", - "note": "The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.\n" + "brief": "A string identifying the remoting system. See below for a list of well-known identifiers.", + "requirement_level": "recommended", + "stability": "experimental" }, { - "name": "android.state", + "name": "rpc.message.type", "type": { - "allow_custom_values": false, + "allow_custom_values": true, "members": [ { - "id": "created", - "value": "created", - "brief": "Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time.\n", - "note": null + "id": "sent", + "value": "SENT", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null }, { - "id": "background", - "value": "background", - "brief": "Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state.\n", - "note": null - }, - { - "id": "foreground", - "value": "foreground", - "brief": "Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states.", - "note": null + "id": "received", + "value": "RECEIVED", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null } ] }, - "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", - "requirement_level": "required", - "note": "The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.\n" + "brief": "Whether this is a received or sent message.", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.message.id", + "type": "int", + "brief": "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message.", + "requirement_level": "recommended", + "note": "This way we guarantee that the values will be consistent between different implementations.", + "stability": "experimental" + }, + { + "name": "rpc.message.compressed_size", + "type": "int", + "brief": "Compressed size of the message in bytes.", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.message.uncompressed_size", + "type": "int", + "brief": "Uncompressed size of the message in bytes.", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "server.address", + "type": "string", + "brief": "Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.", + "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.\n", + "stability": "stable" + }, + { + "name": "server.port", + "type": "int", + "brief": "Server port number.", + "examples": [ + 80, + 8080, + 443 + ], + "requirement_level": "recommended", + "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.\n", + "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.\n", + "examples": [ + "java.net.ConnectException", + "OSError" + ], + "requirement_level": { + "conditionally_required": "Required if `exception.message` is not set, recommended otherwise." + }, + "stability": "stable" + }, + { + "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." + }, + "stability": "stable" }, { "name": "feature_flag.key", @@ -98,5 +1427,616 @@ ], "requirement_level": "recommended", "note": "A semantic identifier, commonly referred to as a variant, provides a means\nfor referring to a value without including the value itself. This can\nprovide additional context for understanding the meaning behind a value.\nFor example, the variant `red` maybe be used for the value `#c05543`.\n\nA stringified version of the value can be used in situations where a\nsemantic identifier is unavailable. String representation of the value\nshould be determined by the implementer." + }, + { + "name": "gen_ai.system", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "openai", + "value": "openai", + "brief": "OpenAI", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "vertex_ai", + "value": "vertex_ai", + "brief": "Vertex AI", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "anthropic", + "value": "anthropic", + "brief": "Anthropic", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cohere", + "value": "cohere", + "brief": "Cohere", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The Generative AI product as identified by the client or server instrumentation.", + "examples": "openai", + "requirement_level": "required", + "note": "The `gen_ai.system` describes a family of GenAI models with specific model identified\nby `gen_ai.request.model` and `gen_ai.response.model` attributes.\n\nThe actual GenAI product may differ from the one identified by the client.\nFor example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system`\nis set to `openai` based on the instrumentation's best knowledge.\n\nFor custom model, a custom friendly name SHOULD be used.\nIf none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.\n", + "stability": "experimental" + }, + { + "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": "required", + "note": "The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.\n", + "stability": "experimental" + }, + { + "name": "gen_ai.operation.name", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "chat", + "value": "chat", + "brief": "Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "text_completion", + "value": "text_completion", + "brief": "Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions)", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "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.\n", + "stability": "experimental" + }, + { + "name": "gen_ai.response.model", + "type": "string", + "brief": "The name of the model that generated the response.", + "examples": [ + "gpt-4-0613" + ], + "requirement_level": "recommended", + "note": "If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned.\n", + "stability": "experimental" + }, + { + "name": "gen_ai.prompt", + "type": "string", + "brief": "The full prompt sent to the GenAI model.", + "examples": [ + "[{'role': 'user', 'content': 'What is the capital of France?'}]" + ], + "requirement_level": { + "conditionally_required": "if and only if corresponding event is enabled" + }, + "note": "It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)\n", + "stability": "experimental" + }, + { + "name": "gen_ai.completion", + "type": "string", + "brief": "The full response received from the GenAI model.", + "examples": [ + "[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]" + ], + "requirement_level": { + "conditionally_required": "if and only if corresponding event is enabled" + }, + "note": "It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation)\n", + "stability": "experimental" + }, + { + "name": "rpc.system", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "grpc", + "value": "grpc", + "brief": "gRPC", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "java_rmi", + "value": "java_rmi", + "brief": "Java RMI", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "dotnet_wcf", + "value": "dotnet_wcf", + "brief": ".NET WCF", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "apache_dubbo", + "value": "apache_dubbo", + "brief": "Apache Dubbo", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "connect_rpc", + "value": "connect_rpc", + "brief": "Connect RPC", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "A string identifying the remoting system. See below for a list of well-known identifiers.", + "requirement_level": "required", + "stability": "experimental" + }, + { + "name": "server.address", + "type": "string", + "brief": "RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html).\n", + "examples": [ + "example.com", + "10.1.2.80", + "/tmp/my.sock" + ], + "requirement_level": "required", + "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.\n", + "stability": "stable" + }, + { + "name": "server.port", + "type": "int", + "brief": "Server port number.", + "examples": [ + 80, + 8080, + 443 + ], + "requirement_level": { + "conditionally_required": "if the port is supported by the network transport used for communication." + }, + "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.\n", + "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.grpc.request.metadata", + "type": "template[string[]]", + "brief": "gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.grpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]" + ], + "tag": "grpc-tech-specific", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.grpc.response.metadata", + "type": "template[string[]]", + "brief": "gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.grpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]" + ], + "tag": "grpc-tech-specific", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.grpc.status_code", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "ok", + "value": 0, + "brief": "OK", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "cancelled", + "value": 1, + "brief": "CANCELLED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unknown", + "value": 2, + "brief": "UNKNOWN", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "invalid_argument", + "value": 3, + "brief": "INVALID_ARGUMENT", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "deadline_exceeded", + "value": 4, + "brief": "DEADLINE_EXCEEDED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "not_found", + "value": 5, + "brief": "NOT_FOUND", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "already_exists", + "value": 6, + "brief": "ALREADY_EXISTS", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "permission_denied", + "value": 7, + "brief": "PERMISSION_DENIED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "resource_exhausted", + "value": 8, + "brief": "RESOURCE_EXHAUSTED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "failed_precondition", + "value": 9, + "brief": "FAILED_PRECONDITION", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "aborted", + "value": 10, + "brief": "ABORTED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "out_of_range", + "value": 11, + "brief": "OUT_OF_RANGE", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unimplemented", + "value": 12, + "brief": "UNIMPLEMENTED", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "internal", + "value": 13, + "brief": "INTERNAL", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unavailable", + "value": 14, + "brief": "UNAVAILABLE", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "data_loss", + "value": 15, + "brief": "DATA_LOSS", + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unauthenticated", + "value": 16, + "brief": "UNAUTHENTICATED", + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request.", + "tag": "grpc-tech-specific", + "requirement_level": "required", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.error_code", + "type": "int", + "brief": "`error.code` property of response if it is an error response.", + "examples": [ + -32700, + 100 + ], + "tag": "jsonrpc-tech-specific", + "requirement_level": { + "conditionally_required": "If response is not successful." + }, + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.error_message", + "type": "string", + "brief": "`error.message` property of response if it is an error response.", + "examples": [ + "Parse error", + "User already exists" + ], + "tag": "jsonrpc-tech-specific", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.request_id", + "type": "string", + "brief": "`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification.\n", + "examples": [ + "10", + "request-7", + "" + ], + "tag": "jsonrpc-tech-specific", + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "rpc.jsonrpc.version", + "type": "string", + "brief": "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted.", + "examples": [ + "2.0", + "1.0" + ], + "tag": "jsonrpc-tech-specific", + "requirement_level": { + "conditionally_required": "If other than the default version (`1.0`)" + }, + "stability": "experimental" + }, + { + "name": "rpc.method", + "type": "string", + "brief": "The name of the (logical) method being called, must be equal to the $method part in the span name.", + "examples": "exampleMethod", + "tag": "jsonrpc-tech-specific", + "requirement_level": "required", + "note": "This is always required for jsonrpc. See the note in the general RPC conventions for more information.\n", + "stability": "experimental" + }, + { + "name": "rpc.connect_rpc.error_code", + "type": { + "allow_custom_values": true, + "members": [ + { + "id": "cancelled", + "value": "cancelled", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unknown", + "value": "unknown", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "invalid_argument", + "value": "invalid_argument", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "deadline_exceeded", + "value": "deadline_exceeded", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "not_found", + "value": "not_found", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "already_exists", + "value": "already_exists", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "permission_denied", + "value": "permission_denied", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "resource_exhausted", + "value": "resource_exhausted", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "failed_precondition", + "value": "failed_precondition", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "aborted", + "value": "aborted", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "out_of_range", + "value": "out_of_range", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unimplemented", + "value": "unimplemented", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "internal", + "value": "internal", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unavailable", + "value": "unavailable", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "data_loss", + "value": "data_loss", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + }, + { + "id": "unauthenticated", + "value": "unauthenticated", + "brief": null, + "note": null, + "stability": "experimental", + "deprecated": null + } + ] + }, + "brief": "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values.", + "tag": "connect_rpc-tech-specific", + "requirement_level": { + "conditionally_required": "If response is not successful and if error code available." + }, + "stability": "experimental" + }, + { + "name": "rpc.connect_rpc.request.metadata", + "type": "template[string[]]", + "brief": "Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.request.metadata.my-custom-metadata-attribute=[\"1.2.3.4\", \"1.2.3.5\"]" + ], + "tag": "connect_rpc-tech-specific", + "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.\n", + "stability": "experimental" + }, + { + "name": "rpc.connect_rpc.response.metadata", + "type": "template[string[]]", + "brief": "Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values.\n", + "examples": [ + "rpc.response.metadata.my-custom-metadata-attribute=[\"attribute_value\"]" + ], + "tag": "connect_rpc-tech-specific", + "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.\n", + "stability": "experimental" } ] \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/expected-event-catalog.json b/crates/weaver_resolver/data/registry-test-4-events/expected-event-catalog.json new file mode 100644 index 00000000..bfc7ebe7 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/expected-event-catalog.json @@ -0,0 +1,140 @@ +[ + { + "name": "ios.state", + "type": { + "allow_custom_values": false, + "members": [ + { + "id": "active", + "value": "active", + "brief": "The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.\n", + "note": null + }, + { + "id": "inactive", + "value": "inactive", + "brief": "The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.\n", + "note": null + }, + { + "id": "background", + "value": "background", + "brief": "The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`.\n", + "note": null + }, + { + "id": "foreground", + "value": "foreground", + "brief": "The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`.\n", + "note": null + }, + { + "id": "terminate", + "value": "terminate", + "brief": "The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.\n", + "note": null + } + ] + }, + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "requirement_level": "required", + "note": "The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.\n" + }, + { + "name": "android.state", + "type": { + "allow_custom_values": false, + "members": [ + { + "id": "created", + "value": "created", + "brief": "Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time.\n", + "note": null + }, + { + "id": "background", + "value": "background", + "brief": "Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state.\n", + "note": null + }, + { + "id": "foreground", + "value": "foreground", + "brief": "Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states.", + "note": null + } + ] + }, + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "requirement_level": "required", + "note": "The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.\n" + }, + { + "name": "feature_flag.key", + "type": "string", + "brief": "The unique identifier of the feature flag.", + "examples": [ + "logo-color" + ], + "requirement_level": "required" + }, + { + "name": "feature_flag.provider_name", + "type": "string", + "brief": "The name of the service provider that performs the flag evaluation.", + "examples": [ + "Flag Manager" + ], + "requirement_level": "recommended" + }, + { + "name": "feature_flag.variant", + "type": "string", + "brief": "SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used.\n", + "examples": [ + "red", + "true", + "on" + ], + "requirement_level": "recommended", + "note": "A semantic identifier, commonly referred to as a variant, provides a means\nfor referring to a value without including the value itself. This can\nprovide additional context for understanding the meaning behind a value.\nFor example, the variant `red` maybe be used for the value `#c05543`.\n\nA stringified version of the value can be used in situations where a\nsemantic identifier is unavailable. String representation of the value\nshould be determined by the implementer." + }, + { + "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.\n", + "examples": [ + "java.net.ConnectException", + "OSError" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "name": "exception.message", + "type": "string", + "brief": "The exception message.", + "examples": [ + "Division by zero", + "Can't convert 'int' object to str implicitly" + ], + "requirement_level": "recommended", + "stability": "experimental" + }, + { + "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.\n", + "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.escaped", + "type": "boolean", + "brief": "SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span.\n", + "requirement_level": "recommended", + "note": "An exception is considered to have escaped (or left) the scope of a span,\nif that span is ended while the exception is still logically \"in flight\".\nThis may be actually \"in flight\" in some languages (e.g. if the exception\nis passed to a Context manager's `__exit__` method in Python) but will\nusually be caught at the point of recording the exception in most languages.\n\nIt is usually not possible to determine at the point where an exception is thrown\nwhether it will escape the scope of a span.\nHowever, it is trivial to know that an exception\nwill escape, if one checks for an active exception just before ending the span,\nas done in the [example for recording span exceptions](#recording-an-exception).\n\nIt follows that an exception may still escape the scope of the span\neven if the `exception.escaped` attribute was not set or set to false,\nsince the event might have been recorded at a time where it was not\nclear whether the exception will escape.", + "stability": "experimental" + } + ] \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/expected-registry.json b/crates/weaver_resolver/data/registry-test-4-events/expected-registry.json index d2db1ae2..f37643b6 100644 --- a/crates/weaver_resolver/data/registry-test-4-events/expected-registry.json +++ b/crates/weaver_resolver/data/registry-test-4-events/expected-registry.json @@ -1,15 +1,221 @@ { "registry_url": "https://127.0.0.1", "groups": [ + { + "id": "registry.browser", + "type": "event", + "brief": "An event that adds global attributes for reuse.\n", + "prefix": "browser", + "attributes": [ + 0, + 1, + 2, + 3 + ], + "name": "browser.test.event", + "lineage": { + "source_file": "data/registry-test-4-events/registry/browser-event.yaml" + }, + "body": { + "fields": [ + { + "name": "some.field", + "type": "string", + "brief": "A field that is not referenced in the attributes", + "examples": [ + "some value" + ], + "requirement_level": "recommended", + "note": "This field is not referenced in the attributes" + } + ] + } + }, + { + "id": "browser.pageview", + "type": "event", + "brief": "This event represents an occurrence of a page view.\n", + "attributes": [ + 1, + 8 + ], + "name": "browser.pageview", + "lineage": { + "source_file": "data/registry-test-4-events/registry/browser-ref-event.yaml", + "attributes": { + "browser.platform": { + "source_group": "registry.browser", + "inherited_fields": [ + "brief", + "examples", + "note", + "requirement_level" + ] + }, + "session.id": { + "source_group": "referenced.attributes", + "inherited_fields": [ + "brief", + "examples", + "note", + "requirement_level", + "stability" + ] + } + } + }, + "body": { + "fields": [ + { + "name": "referrer", + "attr": 6, + "alias": "referrer", + "type": "string", + "brief": "This attribute represents the referring page (if available).", + "examples": [ + "https://example.com" + ], + "requirement_level": "recommended", + "note": "Referring Page URI (`document.referrer`) whenever available. The user agent SHOULD NOT send the fragment (`#` followed by more data) portion of the URI.\n", + "stability": "stable" + }, + { + "name": "title", + "type": "string", + "brief": "This attribute represents the title of the page that was viewed.\n", + "examples": [ + "Wikipedia - The Free Encyclopedia" + ], + "requirement_level": "recommended", + "note": "The document title (`document.title`) of the page that was viewed. It MAY be equal to the `url` attribute or empty if it is not applicable.\n" + }, + { + "name": "url", + "attr": 6, + "alias": "url", + "type": "string", + "brief": "This attribute represents the URL of the page that was viewed.\n", + "examples": [ + "https://en.wikipedia.org/wiki/Main_Page", + "https://en.wikipedia.org/wiki/Main_Page#foo" + ], + "requirement_level": "recommended", + "note": "Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. The fragment may be used for `virtual_page`s to disambiguate pages with the same URL (e.g., due to pagination).\n", + "stability": "stable" + }, + { + "name": "type", + "type": { + "allow_custom_values": false, + "members": [ + { + "id": "physical_page", + "value": "0", + "brief": "Initial page load within the browser and will generally also precede a PageNavigationTiming event.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "virtual_page", + "value": "1", + "brief": "This is for Single Page Applications (SPA) where the framework provides the ability to perform client side only page \"navigation\", the exact definition of what a virtual page change is determined by the SPA and the framework it is using.\n", + "note": null, + "stability": null, + "deprecated": null + } + ] + }, + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "requirement_level": "recommended", + "note": "This identifies the type of page view. For example, if the page view represents a user \n" + } + ] + } + }, + { + "id": "client.exception.event", + "type": "event", + "brief": "This document defines the log event used to report a client exception.\n", + "attributes": [ + 4 + ], + "name": "client.exception.event", + "lineage": { + "source_file": "data/registry-test-4-events/registry/client-exception-event.yaml" + }, + "body": { + "fields": [ + { + "name": "type", + "type": "string", + "brief": "The type of the exception.\n", + "examples": [ + "java.net.ConnectException", + "OSError" + ], + "requirement_level": "recommended" + }, + { + "name": "message", + "type": "string", + "brief": "The exception message.", + "examples": [ + "Division by zero", + "Can't convert 'int' object to str implicitly" + ], + "requirement_level": "recommended" + }, + { + "name": "stacktrace", + "type": "string", + "brief": "A stacktrace.\n", + "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" + }, + { + "name": "escaped", + "type": "boolean", + "brief": "SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span.\n", + "requirement_level": "recommended", + "note": "An exception is considered to have escaped." + } + ] + } + }, + { + "id": "log_event_attributes_only", + "type": "event", + "brief": "brief", + "attributes": [ + 7 + ], + "name": "some.event", + "lineage": { + "source_file": "data/registry-test-4-events/registry/log-event.yaml", + "attributes": { + "log.event.attr": { + "source_group": "referenced.attributes", + "inherited_fields": [ + "brief", + "examples", + "note", + "requirement_level", + "stability" + ] + } + } + } + }, { "id": "log-feature_flag", "type": "event", "brief": "This document defines attributes for feature flag evaluations represented using Log Records.\n", "prefix": "feature_flag", "attributes": [ - 2, - 3, - 4 + 69, + 70, + 71 ], "lineage": { "source_file": "data/registry-test-4-events/registry/log-feature_flag.yaml", @@ -45,29 +251,319 @@ } }, { - "id": "ios.lifecycle.events", + "id": "device.app.lifecycle", "type": "event", - "brief": "This event represents an occurrence of a lifecycle transition on the iOS platform.\n", - "prefix": "ios", - "attributes": [ - 0 - ], + "brief": "This event represents an occurrence of a lifecycle transition on Android or iOS platform.\n", + "note": "This event identifies the fields that are common to all lifecycle events for android and iOS using the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are mutually exclusive.\n", + "stability": "experimental", + "attributes": [], "name": "device.app.lifecycle", "lineage": { "source_file": "data/registry-test-4-events/registry/mobile-events.yaml" + }, + "body": { + "fields": [ + { + "name": "ios.state", + "type": { + "allow_custom_values": false, + "members": [ + { + "id": "active", + "value": "active", + "brief": "The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "inactive", + "value": "inactive", + "brief": "The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "background", + "value": "background", + "brief": "The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "foreground", + "value": "foreground", + "brief": "The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "terminate", + "value": "terminate", + "brief": "The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.\n", + "note": null, + "stability": null, + "deprecated": null + } + ] + }, + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "requirement_level": { + "conditionally_required": "if and only if `os.name` is `ios`" + }, + "note": "The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived.\n", + "stability": "experimental" + }, + { + "name": "android.state", + "type": { + "allow_custom_values": false, + "members": [ + { + "id": "created", + "value": "created", + "brief": "Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "background", + "value": "background", + "brief": "Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state.\n", + "note": null, + "stability": null, + "deprecated": null + }, + { + "id": "foreground", + "value": "foreground", + "brief": "Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states.", + "note": null, + "stability": null, + "deprecated": null + } + ] + }, + "brief": "This attribute represents the state the application has transitioned into at the occurrence of the event.\n", + "requirement_level": { + "conditionally_required": "if and only if `os.name` is `android`" + }, + "note": "The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived.\n", + "stability": "experimental" + } + ] } }, { - "id": "android.lifecycle.events", + "id": "log_event_empty", "type": "event", - "brief": "This event represents an occurrence of a lifecycle transition on the Android platform.\n", - "prefix": "android", + "brief": "brief", + "attributes": [], + "name": "ping.event", + "lineage": { + "source_file": "data/registry-test-4-events/registry/ping-event.yaml" + } + }, + { + "id": "referenced.attributes", + "type": "attribute_group", + "brief": "These attributes are used as references for the test below\n", "attributes": [ - 1 + 5, + 6, + 7, + 8 ], - "name": "device.app.lifecycle", "lineage": { - "source_file": "data/registry-test-4-events/registry/mobile-events.yaml" + "source_file": "data/registry-test-4-events/registry/referenced-attributes.yaml" + } + }, + { + "id": "registry.client", + "type": "attribute_group", + "brief": "These attributes may be used to describe the client in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the \"user-facing\" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.\n", + "prefix": "client", + "attributes": [ + 9, + 10 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/referenced-client.yaml" + } + }, + { + "id": "registry.exception", + "type": "attribute_group", + "brief": "This document defines the shared attributes used to report a single exception associated with a span or log.\n", + "prefix": "exception", + "attributes": [ + 11, + 12, + 13, + 14 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/referenced-exception.yaml" + } + }, + { + "id": "registry.gen_ai", + "type": "attribute_group", + "brief": "This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses.\n", + "prefix": "gen_ai", + "attributes": [ + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23, + 24, + 25, + 26, + 27, + 28, + 29, + 30, + 31, + 32 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/referenced-gen_ai.yaml" + } + }, + { + "id": "registry.network", + "type": "attribute_group", + "brief": "These attributes may be used for any network related operation.\n", + "prefix": "network", + "attributes": [ + 33, + 34, + 35, + 36, + 37, + 38, + 39, + 40, + 41, + 42, + 43, + 44, + 45, + 46, + 47 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/referenced-network.yaml" + } + }, + { + "id": "registry.rpc", + "type": "attribute_group", + "brief": "This document defines attributes for remote procedure calls.", + "prefix": "rpc", + "attributes": [ + 48, + 49, + 50, + 51, + 52, + 53, + 54, + 55, + 56, + 57, + 58, + 59, + 60, + 61, + 62, + 63, + 64 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/referenced-rpc.yaml" + } + }, + { + "id": "registry.server", + "type": "attribute_group", + "brief": "These attributes may be used to describe the server in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the \"user-facing\" surface of the protocol / API doesn't expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.\n", + "prefix": "server", + "attributes": [ + 65, + 66 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/referenced-server.yaml" + } + }, + { + "id": "trace-exception", + "type": "event", + "brief": "This document defines the attributes used to report a single exception associated with a span.\n", + "prefix": "exception", + "attributes": [ + 13, + 14, + 67, + 68 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-exception.yaml", + "attributes": { + "exception.escaped": { + "source_group": "registry.exception", + "inherited_fields": [ + "brief", + "note", + "requirement_level", + "stability" + ] + }, + "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" + ] + } + } } }, { @@ -76,13 +572,1172 @@ "brief": "This semantic convention defines the attributes used to represent a feature flag evaluation as an event.\n", "prefix": "feature_flag", "attributes": [ - 2, - 3, - 4 + 69, + 70, + 71 ], "lineage": { "source_file": "data/registry-test-4-events/registry/trace-feature-flag.yaml" } + }, + { + "id": "trace.gen_ai.client", + "type": "span", + "brief": "Describes GenAI operation span.\n", + "attributes": [ + 17, + 18, + 19, + 20, + 21, + 22, + 23, + 24, + 26, + 27, + 28, + 72, + 73, + 74, + 75 + ], + "events": [ + "gen_ai.content.prompt", + "gen_ai.content.completion" + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-gen-ai.yaml", + "attributes": { + "gen_ai.operation.name": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.frequency_penalty": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.max_tokens": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.model": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "stability" + ], + "locally_overridden_fields": [ + "note", + "requirement_level" + ] + }, + "gen_ai.request.presence_penalty": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.stop_sequences": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.temperature": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.top_k": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.request.top_p": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability", + "tag" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.response.finish_reasons": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.response.id": { + "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", + "stability" + ], + "locally_overridden_fields": [ + "note", + "requirement_level" + ] + }, + "gen_ai.system": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.usage.input_tokens": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "gen_ai.usage.output_tokens": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "gen_ai.content.prompt", + "type": "event", + "brief": "In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation.\n", + "attributes": [ + 76 + ], + "name": "gen_ai.content.prompt", + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-gen-ai.yaml", + "attributes": { + "gen_ai.prompt": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "stability" + ], + "locally_overridden_fields": [ + "note", + "requirement_level" + ] + } + } + } + }, + { + "id": "gen_ai.content.completion", + "type": "event", + "brief": "In the lifetime of an GenAI span, events for prompts sent and completions received may be created, depending on the configuration of the instrumentation.\n", + "attributes": [ + 77 + ], + "name": "gen_ai.content.completion", + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-gen-ai.yaml", + "attributes": { + "gen_ai.completion": { + "source_group": "registry.gen_ai", + "inherited_fields": [ + "brief", + "examples", + "stability" + ], + "locally_overridden_fields": [ + "note", + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc", + "type": "span", + "brief": "This document defines semantic conventions for remote procedure calls.", + "prefix": "rpc", + "attributes": [ + 45, + 46, + 58, + 59, + 78, + 79, + 80 + ], + "events": [ + "rpc.message" + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.yaml", + "attributes": { + "network.transport": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.type": { + "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" + ] + }, + "rpc.service": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.system": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "server.address": { + "source_group": "registry.server", + "inherited_fields": [ + "examples", + "stability" + ], + "locally_overridden_fields": [ + "brief", + "note", + "requirement_level" + ] + }, + "server.port": { + "source_group": "registry.server", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc.client", + "type": "span", + "brief": "This document defines semantic conventions for remote procedure call client spans.", + "attributes": [ + 41, + 45, + 46, + 58, + 59, + 78, + 79, + 80, + 81 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.yaml", + "attributes": { + "network.peer.address": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.peer.port": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.transport": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.type": { + "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" + ] + }, + "rpc.service": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.system": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "server.address": { + "source_group": "registry.server", + "inherited_fields": [ + "examples", + "stability" + ], + "locally_overridden_fields": [ + "brief", + "note", + "requirement_level" + ] + }, + "server.port": { + "source_group": "registry.server", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc.server", + "type": "span", + "brief": "Semantic Convention for RPC server spans", + "attributes": [ + 9, + 10, + 41, + 45, + 46, + 58, + 59, + 78, + 79, + 80, + 81 + ], + "span_kind": "server", + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.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" + ] + }, + "network.peer.address": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.peer.port": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.transport": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.type": { + "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" + ] + }, + "rpc.service": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.system": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "server.address": { + "source_group": "registry.server", + "inherited_fields": [ + "examples", + "stability" + ], + "locally_overridden_fields": [ + "brief", + "note", + "requirement_level" + ] + }, + "server.port": { + "source_group": "registry.server", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc.grpc", + "type": "span", + "brief": "Tech-specific attributes for gRPC.", + "attributes": [ + 45, + 46, + 58, + 59, + 78, + 79, + 80, + 82, + 83, + 84 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.yaml", + "attributes": { + "network.transport": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.type": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.grpc.request.metadata": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.grpc.response.metadata": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.grpc.status_code": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.method": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.service": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.system": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "server.address": { + "source_group": "registry.server", + "inherited_fields": [ + "examples", + "stability" + ], + "locally_overridden_fields": [ + "brief", + "note", + "requirement_level" + ] + }, + "server.port": { + "source_group": "registry.server", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc.jsonrpc", + "type": "span", + "brief": "Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).", + "prefix": "rpc.jsonrpc", + "attributes": [ + 45, + 46, + 59, + 78, + 79, + 80, + 85, + 86, + 87, + 88, + 89 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.yaml", + "attributes": { + "network.transport": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.type": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.jsonrpc.error_code": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.jsonrpc.error_message": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.jsonrpc.request_id": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.jsonrpc.version": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.method": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "stability" + ], + "locally_overridden_fields": [ + "note", + "requirement_level", + "tag" + ] + }, + "rpc.service": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.system": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "server.address": { + "source_group": "registry.server", + "inherited_fields": [ + "examples", + "stability" + ], + "locally_overridden_fields": [ + "brief", + "note", + "requirement_level" + ] + }, + "server.port": { + "source_group": "registry.server", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc.message", + "type": "event", + "brief": "RPC received/sent message.", + "prefix": "rpc.message", + "attributes": [ + 61, + 62, + 63, + 64 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.yaml", + "attributes": { + "rpc.message.compressed_size": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.message.id": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.message.type": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.message.uncompressed_size": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } + }, + { + "id": "rpc.connect_rpc", + "type": "span", + "brief": "Tech-specific attributes for Connect RPC.", + "attributes": [ + 45, + 46, + 58, + 59, + 78, + 79, + 80, + 90, + 91, + 92 + ], + "lineage": { + "source_file": "data/registry-test-4-events/registry/trace-rpc.yaml", + "attributes": { + "network.transport": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "network.type": { + "source_group": "registry.network", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.connect_rpc.error_code": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.connect_rpc.request.metadata": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.connect_rpc.response.metadata": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level", + "tag" + ] + }, + "rpc.method": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.service": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "rpc.system": { + "source_group": "registry.rpc", + "inherited_fields": [ + "brief", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + }, + "server.address": { + "source_group": "registry.server", + "inherited_fields": [ + "examples", + "stability" + ], + "locally_overridden_fields": [ + "brief", + "note", + "requirement_level" + ] + }, + "server.port": { + "source_group": "registry.server", + "inherited_fields": [ + "brief", + "examples", + "note", + "stability" + ], + "locally_overridden_fields": [ + "requirement_level" + ] + } + } + } } ] } \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/browser-event.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/browser-event.yaml new file mode 100644 index 00000000..7de8f67b --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/browser-event.yaml @@ -0,0 +1,54 @@ +groups: + - id: registry.browser + name: browser.test.event + prefix: browser + type: event + brief: > + An event that adds global attributes for reuse. + attributes: + - id: brands + type: string[] + brief: 'Array of brand name and version separated by a space' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.brands`). + examples: [ " Not A;Brand 99", "Chromium 99", "Chrome 99" ] + - id: platform + type: string + brief: 'The platform on which the browser is running' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.platform`). If unavailable, the legacy + `navigator.platform` API SHOULD NOT be used instead and this attribute + SHOULD be left unset in order for the values to be consistent. + The list of possible values is defined in the + [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). + Note that some (but not all) of these values can overlap with values + in the [`os.type` and `os.name` attributes](./os.md). + However, for consistency, the values in the `browser.platform` attribute + should capture the exact value that the user agent provides. + examples: ['Windows', 'macOS', 'Android'] + - id: mobile + type: boolean + brief: 'A boolean that is true if the browser is running on a mobile device' + note: > + This value is intended to be taken from the + [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) + (`navigator.userAgentData.mobile`). If unavailable, this attribute + SHOULD be left unset. + - id: language + type: string + brief: 'Preferred language of the user using the browser' + note: > + This value is intended to be taken from the Navigator API + `navigator.language`. + examples: ["en", "en-US", "fr", "fr-FR"] + body: + fields: + - id: some.field + type: string + brief: 'A field that is not referenced in the attributes' + note: 'This field is not referenced in the attributes' + examples: ['some value'] \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/browser-ref-event.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/browser-ref-event.yaml new file mode 100644 index 00000000..ef216d23 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/browser-ref-event.yaml @@ -0,0 +1,52 @@ +groups: + - id: browser.pageview + name: browser.pageview + type: event + brief: > + This event represents an occurrence of a page view. + attributes: + - ref: session.id + - ref: browser.platform + body: + fields: + - ref: http.url + alias: referrer + note: > + Referring Page URI (`document.referrer`) whenever available. The user agent SHOULD NOT send the fragment + (`#` followed by more data) portion of the URI. + brief: This attribute represents the referring page (if available). + - id: title + brief: > + This attribute represents the title of the page that was viewed. + note: > + The document title (`document.title`) of the page that was viewed. It MAY be equal to the `url` attribute + or empty if it is not applicable. + type: string + examples: ['Wikipedia - The Free Encyclopedia'] + - ref: http.url + alias: url + note: > + Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is + not transmitted over HTTP, but if it is known, it should be included nevertheless. The fragment may be + used for `virtual_page`s to disambiguate pages with the same URL (e.g., due to pagination). + brief: > + This attribute represents the URL of the page that was viewed. + examples: ['https://en.wikipedia.org/wiki/Main_Page', 'https://en.wikipedia.org/wiki/Main_Page#foo'] + - id: type + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + note: > + This identifies the type of page view. For example, if the page view represents a user + type: + allow_custom_values: false + members: + - id: physical_page + value: '0' + brief: > + Initial page load within the browser and will generally also precede a PageNavigationTiming event. + - id: virtual_page + value: '1' + brief: > + This is for Single Page Applications (SPA) where the framework provides the ability to perform + client side only page "navigation", the exact definition of what a virtual page change is determined + by the SPA and the framework it is using. diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/client-exception-event.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/client-exception-event.yaml new file mode 100644 index 00000000..5e6819fa --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/client-exception-event.yaml @@ -0,0 +1,39 @@ +groups: + - id: client.exception.event + name: client.exception.event + type: event + brief: > + This document defines the log event used to + report a client exception. + body: + fields: + - id: type + type: string + brief: > + The type of the exception. + examples: ["java.net.ConnectException","OSError"] + - id: message + type: string + brief: The exception message. + examples: ["Division by zero","Can't convert 'int' object to str implicitly"] + - id: stacktrace + type: string + brief: > + A stacktrace. + 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)' + - id: escaped + type: boolean + brief: > + SHOULD be set to true if the exception event is recorded at a point where + it is known that the exception is escaping the scope of the span. + note: |- + An exception is considered to have escaped. + attributes: + - id: client.name + type: string + brief: > + The name of the client that reported the exception. + examples: ["myclient"] \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/log-event.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/log-event.yaml new file mode 100644 index 00000000..e2556e1b --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/log-event.yaml @@ -0,0 +1,7 @@ +groups: + - id: log_event_attributes_only + name: some.event + type: event + brief: brief + attributes: + - ref: log.event.attr diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/mobile-events.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/mobile-events.yaml index 94f93ebb..b1b219d5 100644 --- a/crates/weaver_resolver/data/registry-test-4-events/registry/mobile-events.yaml +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/mobile-events.yaml @@ -1,72 +1,74 @@ groups: - - id: ios.lifecycle.events + - id: device.app.lifecycle + stability: experimental type: event - prefix: ios name: device.app.lifecycle brief: > - This event represents an occurrence of a lifecycle transition on the iOS platform. - attributes: - - id: state - requirement_level: "required" - note: > - The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), - and from which the `OS terminology` column values are derived. - brief: > - This attribute represents the state the application has transitioned into at the occurrence of the event. - type: - allow_custom_values: false - members: - - id: active - value: 'active' - brief: > - The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. - - id: inactive - value: 'inactive' - brief: > - The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. - - id: background - value: 'background' - brief: > - The app is now in the background. - This value is associated with UIKit notification `applicationDidEnterBackground`. - - id: foreground - value: 'foreground' - brief: > - The app is now in the foreground. - This value is associated with UIKit notification `applicationWillEnterForeground`. - - id: terminate - value: 'terminate' - brief: > - The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. - - id: android.lifecycle.events - type: event - prefix: android - name: device.app.lifecycle - brief: > - This event represents an occurrence of a lifecycle transition on the Android platform. - attributes: - - id: state - requirement_level: required - brief: > - This attribute represents the state the application has transitioned into at the occurrence of the event. - note: > - The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), - and from which the `OS identifiers` are derived. - type: - allow_custom_values: false - members: - - id: created - value: 'created' - brief: > - Any time before Activity.onResume() or, if the app has no Activity, Context.startService() - has been called in the app for the first time. - - id: background - value: 'background' - brief: > - Any time after Activity.onPause() or, if the app has no Activity, - Context.stopService() has been called when the app was in the foreground state. - - id: foreground - value: 'foreground' - brief: > - Any time after Activity.onResume() or, if the app has no Activity, - Context.startService() has been called when the app was in either the created or background states. \ No newline at end of file + This event represents an occurrence of a lifecycle transition on Android or iOS platform. + note: > + This event identifies the fields that are common to all lifecycle events for android and iOS using + the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are + mutually exclusive. + body: + fields: + - id: ios.state + stability: experimental + requirement_level: + conditionally_required: if and only if `os.name` is `ios` + note: > + The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), + and from which the `OS terminology` column values are derived. + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + type: + allow_custom_values: false + members: + - id: active + value: 'active' + brief: > + The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + - id: inactive + value: 'inactive' + brief: > + The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + - id: background + value: 'background' + brief: > + The app is now in the background. + This value is associated with UIKit notification `applicationDidEnterBackground`. + - id: foreground + value: 'foreground' + brief: > + The app is now in the foreground. + This value is associated with UIKit notification `applicationWillEnterForeground`. + - id: terminate + value: 'terminate' + brief: > + The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + - id: android.state + stability: experimental + requirement_level: + conditionally_required: if and only if `os.name` is `android` + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + note: > + The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), + and from which the `OS identifiers` are derived. + type: + allow_custom_values: false + members: + - id: created + value: 'created' + brief: > + Any time before Activity.onResume() or, if the app has no Activity, Context.startService() + has been called in the app for the first time. + - id: background + value: 'background' + brief: > + Any time after Activity.onPause() or, if the app has no Activity, + Context.stopService() has been called when the app was in the foreground state. + - id: foreground + value: 'foreground' + brief: > + Any time after Activity.onResume() or, if the app has no Activity, + Context.startService() has been called when the app was in either the created or background states. \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/ping-event.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/ping-event.yaml new file mode 100644 index 00000000..a9ea856e --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/ping-event.yaml @@ -0,0 +1,5 @@ +groups: + - id: log_event_empty + name: ping.event + type: event + brief: brief \ No newline at end of file diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-attributes.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-attributes.yaml new file mode 100644 index 00000000..8dad8dd0 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-attributes.yaml @@ -0,0 +1,32 @@ +groups: + + # As the tests are only loading a subset of files we need to define any referenced attributes before they can be resolved for body fields + - id: referenced.attributes + type: attribute_group + brief: > + These attributes are used as references for the test below + attributes: + - id: browser.platform + stability: stable + type: string + brief: 'The browser platform' + note: Test value. + examples: ['Windows', 'macOS', 'Android'] + - id: http.url + stability: stable + type: string + brief: 'The Url' + note: Test url value. + examples: ['https://example.com'] + - id: log.event.attr + stability: stable + type: string + brief: 'Just making sure the referenced attributes are defined' + note: Test value. + examples: some value + - id: session.id + stability: stable + type: string + brief: 'The session id' + note: Test value. + examples: 127836abcdef98 diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-client.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-client.yaml new file mode 100644 index 00000000..3b17ed8b --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-client.yaml @@ -0,0 +1,28 @@ +groups: + - id: registry.client + prefix: client + type: attribute_group + brief: > + These attributes may be used to describe the client in a connection-based network interaction + where there is one side that initiates the connection (the client is the side that initiates the connection). + This covers all TCP network interactions since TCP is connection-based and one side initiates the + connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the + protocol / API doesn't expose a clear notion of client and server). + This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + attributes: + - id: address + stability: stable + type: string + brief: "Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + 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. + examples: ['client.example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + stability: stable + type: int + brief: Client port number. + examples: [65123] + 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. diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-exception.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-exception.yaml new file mode 100644 index 00000000..3044fe69 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-exception.yaml @@ -0,0 +1,55 @@ +groups: + - id: registry.exception + type: attribute_group + prefix: exception + brief: > + This document defines the shared attributes used to + report a single exception associated with a span or log. + attributes: + - id: type + type: string + stability: stable + 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"] + - id: message + type: string + stability: stable + brief: The exception message. + examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] + - id: stacktrace + type: string + stability: stable + 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)' + - id: escaped + type: boolean + stability: stable + brief: > + SHOULD be set to true if the exception event is recorded at a point where + it is known that the exception is escaping the scope of the span. + note: |- + An exception is considered to have escaped (or left) the scope of a span, + if that span is ended while the exception is still logically "in flight". + This may be actually "in flight" in some languages (e.g. if the exception + is passed to a Context manager's `__exit__` method in Python) but will + usually be caught at the point of recording the exception in most languages. + + It is usually not possible to determine at the point where an exception is thrown + whether it will escape the scope of a span. + However, it is trivial to know that an exception + will escape, if one checks for an active exception just before ending the span, + as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). + + It follows that an exception may still escape the scope of the span + even if the `exception.escaped` attribute was not set or set to false, + since the event might have been recorded at a time where it was not + clear whether the exception will escape. + diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-gen_ai.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-gen_ai.yaml new file mode 100644 index 00000000..ce6755a1 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-gen_ai.yaml @@ -0,0 +1,148 @@ +groups: + - id: registry.gen_ai + prefix: gen_ai + type: attribute_group + brief: > + This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses. + attributes: + - id: system + stability: experimental + type: + members: + - id: openai + stability: experimental + value: "openai" + brief: 'OpenAI' + - id: vertex_ai + stability: experimental + value: "vertex_ai" + brief: 'Vertex AI' + - id: anthropic + stability: experimental + value: "anthropic" + brief: 'Anthropic' + - id: cohere + stability: experimental + value: "cohere" + brief: 'Cohere' + brief: The Generative AI product as identified by the client or server instrumentation. + note: | + The `gen_ai.system` describes a family of GenAI models with specific model identified + by `gen_ai.request.model` and `gen_ai.response.model` attributes. + + The actual GenAI product may differ from the one identified by the client. + For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` + is set to `openai` based on the instrumentation's best knowledge. + + For custom model, a custom friendly name SHOULD be used. + If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. + examples: 'openai' + - id: request.model + stability: experimental + type: string + brief: The name of the GenAI model a request is being made to. + examples: 'gpt-4' + - id: request.max_tokens + stability: experimental + type: int + brief: The maximum number of tokens the model generates for a request. + examples: [100] + - id: request.temperature + stability: experimental + type: double + brief: The temperature setting for the GenAI request. + examples: [0.0] + - id: request.top_p + stability: experimental + type: double + brief: The top_p sampling setting for the GenAI request. + examples: [1.0] + tag: llm-generic-request + - id: request.top_k + stability: experimental + type: double + brief: The top_k sampling setting for the GenAI request. + examples: [1.0] + - id: request.stop_sequences + stability: experimental + type: string[] + brief: List of sequences that the model will use to stop generating further tokens. + examples: ['forest', 'lived'] + - id: request.frequency_penalty + stability: experimental + type: double + brief: The frequency penalty setting for the GenAI request. + examples: [0.1] + - id: request.presence_penalty + stability: experimental + type: double + brief: The presence penalty setting for the GenAI request. + examples: [0.1] + - id: response.id + stability: experimental + type: string + brief: The unique identifier for the completion. + examples: ['chatcmpl-123'] + - id: response.model + stability: experimental + type: string + brief: The name of the model that generated the response. + examples: ['gpt-4-0613'] + - id: response.finish_reasons + stability: experimental + type: string[] + brief: Array of reasons the model stopped generating tokens, corresponding to each generation received. + examples: ['stop'] + - id: usage.input_tokens + stability: experimental + type: int + brief: The number of tokens used in the GenAI input (prompt). + examples: [100] + - id: usage.output_tokens + stability: experimental + type: int + brief: The number of tokens used in the GenAI response (completion). + examples: [180] + - id: token.type + stability: experimental + type: + members: + - id: input + stability: experimental + value: "input" + brief: 'Input tokens (prompt, input, etc.)' + - id: completion + stability: experimental + value: "output" + brief: 'Output tokens (completion, response, etc.)' + brief: The type of token being counted. + examples: ['input', 'output'] + - id: prompt + stability: experimental + type: string + brief: The full prompt sent to the GenAI model. + note: It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + examples: ["[{'role': 'user', 'content': 'What is the capital of France?'}]"] + - id: completion + stability: experimental + type: string + brief: The full response received from the GenAI model. + note: It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + examples: ["[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]"] + - id: operation.name + stability: experimental + type: + members: + - id: chat + value: "chat" + brief: 'Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat)' + stability: experimental + - 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: experimental + brief: The name of the operation being performed. + 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. diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-network.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-network.yaml new file mode 100644 index 00000000..2f3f1957 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-network.yaml @@ -0,0 +1,235 @@ +groups: + - id: registry.network + prefix: network + type: attribute_group + brief: > + These attributes may be used for any network related operation. + attributes: + - id: carrier.icc + type: string + stability: experimental + brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." + examples: "DE" + - id: carrier.mcc + type: string + stability: experimental + brief: "The mobile carrier country code." + examples: "310" + - id: carrier.mnc + type: string + stability: experimental + brief: "The mobile carrier network code." + examples: "001" + - id: carrier.name + type: string + stability: experimental + brief: "The name of the mobile carrier." + examples: "sprint" + - id: connection.subtype + type: + allow_custom_values: true + members: + - id: gprs + brief: GPRS + value: "gprs" + stability: experimental + - id: edge + brief: EDGE + value: "edge" + stability: experimental + - id: umts + brief: UMTS + value: "umts" + stability: experimental + - id: cdma + brief: CDMA + value: "cdma" + stability: experimental + - id: evdo_0 + brief: EVDO Rel. 0 + value: "evdo_0" + stability: experimental + - id: evdo_a + brief: "EVDO Rev. A" + value: "evdo_a" + stability: experimental + - id: cdma2000_1xrtt + brief: CDMA2000 1XRTT + value: "cdma2000_1xrtt" + stability: experimental + - id: hsdpa + brief: HSDPA + value: "hsdpa" + stability: experimental + - id: hsupa + brief: HSUPA + value: "hsupa" + stability: experimental + - id: hspa + brief: HSPA + value: "hspa" + stability: experimental + - id: iden + brief: IDEN + value: "iden" + stability: experimental + - id: evdo_b + brief: "EVDO Rev. B" + value: "evdo_b" + stability: experimental + - id: lte + brief: LTE + value: "lte" + stability: experimental + - id: ehrpd + brief: EHRPD + value: "ehrpd" + stability: experimental + - id: hspap + brief: HSPAP + value: "hspap" + stability: experimental + - id: gsm + brief: GSM + value: "gsm" + stability: experimental + - id: td_scdma + brief: TD-SCDMA + value: "td_scdma" + stability: experimental + - id: iwlan + brief: IWLAN + value: "iwlan" + stability: experimental + - id: nr + brief: "5G NR (New Radio)" + value: "nr" + stability: experimental + - id: nrnsa + brief: "5G NRNSA (New Radio Non-Standalone)" + value: "nrnsa" + stability: experimental + - id: lte_ca + brief: LTE CA + value: "lte_ca" + stability: experimental + stability: experimental + brief: 'This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.' + examples: 'LTE' + - id: connection.type + type: + allow_custom_values: true + members: + - id: wifi + value: "wifi" + stability: experimental + - id: wired + value: "wired" + stability: experimental + - id: cell + value: "cell" + stability: experimental + - id: unavailable + value: "unavailable" + stability: experimental + - id: unknown + value: "unknown" + stability: experimental + stability: experimental + brief: 'The internet connection type.' + examples: 'wifi' + - id: local.address + stability: stable + type: string + brief: Local address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: local.port + stability: stable + type: int + brief: Local port number of the network connection. + examples: [65123] + - id: peer.address + stability: stable + type: string + brief: Peer address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: peer.port + stability: stable + type: int + brief: Peer port number of the network connection. + examples: [65123] + - id: protocol.name + stability: stable + type: string + brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. + examples: ['amqp', 'http', 'mqtt'] + - id: protocol.version + stability: stable + type: string + brief: The actual version of the protocol used for network communication. + examples: ['1.1', '2'] + note: > + If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), + this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, + this attribute SHOULD NOT be set. + - id: transport + stability: stable + type: + allow_custom_values: true + members: + - id: tcp + value: 'tcp' + brief: "TCP" + stability: stable + - id: udp + value: 'udp' + brief: "UDP" + stability: stable + - id: pipe + value: "pipe" + brief: 'Named or anonymous pipe.' + stability: stable + - id: unix + value: 'unix' + brief: "Unix domain socket" + stability: stable + brief: > + [OSI transport layer](https://osi-model.com/transport-layer/) or + [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + note: | + The value SHOULD be normalized to lowercase. + + Consider always setting the transport when setting a port number, since + a port number is ambiguous without knowing the transport. For example + different processes could be listening on TCP port 12345 and UDP port 12345. + examples: ['tcp', 'udp'] + - id: type + stability: stable + type: + allow_custom_values: true + members: + - id: ipv4 + value: 'ipv4' + brief: "IPv4" + stability: stable + - id: ipv6 + value: 'ipv6' + brief: "IPv6" + stability: stable + brief: '[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. + examples: ['ipv4', 'ipv6'] + - id: io.direction + type: + allow_custom_values: false + members: + - id: transmit + value: 'transmit' + stability: experimental + - id: receive + value: 'receive' + stability: experimental + stability: experimental + brief: "The network IO operation direction." + examples: ["transmit"] diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-rpc.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-rpc.yaml new file mode 100644 index 00000000..d1e0aa05 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-rpc.yaml @@ -0,0 +1,265 @@ +groups: + - id: registry.rpc + prefix: rpc + type: attribute_group + brief: 'This document defines attributes for remote procedure calls.' + attributes: + - id: connect_rpc.error_code + type: + members: + - id: cancelled + value: cancelled + stability: experimental + - id: unknown + value: unknown + stability: experimental + - id: invalid_argument + value: invalid_argument + stability: experimental + - id: deadline_exceeded + value: deadline_exceeded + stability: experimental + - id: not_found + value: not_found + stability: experimental + - id: already_exists + value: already_exists + stability: experimental + - id: permission_denied + value: permission_denied + stability: experimental + - id: resource_exhausted + value: resource_exhausted + stability: experimental + - id: failed_precondition + value: failed_precondition + stability: experimental + - id: aborted + value: aborted + stability: experimental + - id: out_of_range + value: out_of_range + stability: experimental + - id: unimplemented + value: unimplemented + stability: experimental + - id: internal + value: internal + stability: experimental + - id: unavailable + value: unavailable + stability: experimental + - id: data_loss + value: data_loss + stability: experimental + - id: unauthenticated + value: unauthenticated + stability: experimental + stability: experimental + brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - id: connect_rpc.request.metadata + type: template[string[]] + stability: experimental + brief: > + Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: connect_rpc.response.metadata + type: template[string[]] + stability: experimental + brief: > + Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: grpc.status_code + type: + members: + - id: ok + brief: OK + stability: experimental + value: 0 + - id: cancelled + brief: CANCELLED + stability: experimental + value: 1 + - id: unknown + brief: UNKNOWN + stability: experimental + value: 2 + - id: invalid_argument + brief: INVALID_ARGUMENT + stability: experimental + value: 3 + - id: deadline_exceeded + brief: DEADLINE_EXCEEDED + stability: experimental + value: 4 + - id: not_found + brief: NOT_FOUND + stability: experimental + value: 5 + - id: already_exists + brief: ALREADY_EXISTS + stability: experimental + value: 6 + - id: permission_denied + brief: PERMISSION_DENIED + stability: experimental + value: 7 + - id: resource_exhausted + brief: RESOURCE_EXHAUSTED + stability: experimental + value: 8 + - id: failed_precondition + brief: FAILED_PRECONDITION + stability: experimental + value: 9 + - id: aborted + brief: ABORTED + stability: experimental + value: 10 + - id: out_of_range + brief: OUT_OF_RANGE + stability: experimental + value: 11 + - id: unimplemented + brief: UNIMPLEMENTED + stability: experimental + value: 12 + - id: internal + brief: INTERNAL + stability: experimental + value: 13 + - id: unavailable + brief: UNAVAILABLE + stability: experimental + value: 14 + - id: data_loss + brief: DATA_LOSS + stability: experimental + value: 15 + - id: unauthenticated + brief: UNAUTHENTICATED + stability: experimental + value: 16 + stability: experimental + brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: grpc.request.metadata + type: template[string[]] + stability: experimental + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: grpc.response.metadata + type: template[string[]] + stability: experimental + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + 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. + examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: jsonrpc.error_code + type: int + stability: experimental + brief: "`error.code` property of response if it is an error response." + examples: [-32700, 100] + - id: jsonrpc.error_message + type: string + stability: experimental + brief: "`error.message` property of response if it is an error response." + examples: ['Parse error', 'User already exists'] + - id: jsonrpc.request_id + type: string + stability: experimental + brief: > + `id` property of request or response. + Since protocol allows id to be int, string, `null` or missing (for notifications), + value is expected to be cast to string for simplicity. + Use empty string in case of `null` value. Omit entirely if this is a notification. + examples: ['10', 'request-7', ''] + - id: jsonrpc.version + type: string + stability: experimental + brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted." + examples: ['2.0', '1.0'] + - id: method + type: string + stability: experimental + brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' + note: > + This is the logical name of the method from the RPC interface perspective, + which can be different from the name of any implementing method/function. + The `code.function` attribute may be used to store the latter + (e.g., method actually executing the call on the server side, + RPC client stub method on the client side). + examples: "exampleMethod" + - id: service + type: string + stability: experimental + brief: 'The full (logical) name of the service being called, including its package name, if applicable.' + note: > + This is the logical name of the service from the RPC interface perspective, + which can be different from the name of any implementing class. + The `code.namespace` attribute may be used to store the latter + (despite the attribute name, it may include a class name; + e.g., class with method actually executing the call on the server side, + RPC client stub class on the client side). + examples: "myservice.EchoService" + - id: system + brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' + type: + allow_custom_values: true + members: + - id: grpc + value: 'grpc' + brief: 'gRPC' + stability: experimental + - id: java_rmi + value: 'java_rmi' + brief: 'Java RMI' + stability: experimental + - id: dotnet_wcf + value: 'dotnet_wcf' + brief: '.NET WCF' + stability: experimental + - id: apache_dubbo + value: 'apache_dubbo' + brief: 'Apache Dubbo' + stability: experimental + - id: connect_rpc + value: 'connect_rpc' + brief: 'Connect RPC' + stability: experimental + stability: experimental + - id: message.type + type: + members: + - id: sent + value: "SENT" + stability: experimental + - id: received + value: "RECEIVED" + stability: experimental + stability: experimental + brief: "Whether this is a received or sent message." + - id: message.id + type: int + stability: experimental + brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." + note: "This way we guarantee that the values will be consistent between different implementations." + - id: message.compressed_size + type: int + stability: experimental + brief: "Compressed size of the message in bytes." + - id: message.uncompressed_size + type: int + stability: experimental + brief: "Uncompressed size of the message in bytes." diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-server.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-server.yaml new file mode 100644 index 00000000..d6927fe9 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/referenced-server.yaml @@ -0,0 +1,28 @@ +groups: + - id: registry.server + prefix: server + type: attribute_group + brief: > + These attributes may be used to describe the server in a connection-based network interaction + where there is one side that initiates the connection (the client is the side that initiates the connection). + This covers all TCP network interactions since TCP is connection-based and one side initiates the + connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the + protocol / API doesn't expose a clear notion of client and server). + This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + attributes: + - id: address + stability: stable + type: string + brief: "Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + 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. + examples: ['example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + stability: stable + type: int + brief: Server port number. + 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. + examples: [80, 8080, 443] diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/trace-exception.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/trace-exception.yaml new file mode 100644 index 00000000..32c53f4b --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/trace-exception.yaml @@ -0,0 +1,16 @@ +groups: + - id: trace-exception + prefix: exception + type: event + brief: > + This document defines the attributes used to + report a single exception associated with a span. + attributes: + - ref: exception.type + requirement_level: + conditionally_required: Required if `exception.message` is not set, recommended otherwise. + - ref: exception.message + requirement_level: + conditionally_required: Required if `exception.type` is not set, recommended otherwise. + - ref: exception.stacktrace + - ref: exception.escaped diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/trace-gen-ai.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/trace-gen-ai.yaml new file mode 100644 index 00000000..d036c197 --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/trace-gen-ai.yaml @@ -0,0 +1,73 @@ +groups: + - id: trace.gen_ai.client + type: span + brief: > + Describes GenAI operation span. + attributes: + - ref: gen_ai.system + requirement_level: required + - ref: gen_ai.request.model + requirement_level: required + note: > + The name of the GenAI model a request is being made to. If the model is supplied by a vendor, + then the value must be the exact name of the model requested. If the model is a fine-tuned + custom model, the value should have a more specific name than the base model that's been fine-tuned. + - ref: gen_ai.operation.name + requirement_level: required + - ref: gen_ai.request.max_tokens + requirement_level: recommended + - ref: gen_ai.request.temperature + requirement_level: recommended + - ref: gen_ai.request.top_p + requirement_level: recommended + - ref: gen_ai.request.top_k + requirement_level: recommended + - ref: gen_ai.request.stop_sequences + requirement_level: recommended + - ref: gen_ai.request.frequency_penalty + requirement_level: recommended + - ref: gen_ai.request.presence_penalty + requirement_level: recommended + - ref: gen_ai.response.id + requirement_level: recommended + - ref: gen_ai.response.model + requirement_level: recommended + note: > + If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, + then the value must be the exact name of the model actually used. If the model is a + fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + - ref: gen_ai.response.finish_reasons + requirement_level: recommended + - ref: gen_ai.usage.input_tokens + requirement_level: recommended + - ref: gen_ai.usage.output_tokens + requirement_level: recommended + events: + - gen_ai.content.prompt + - gen_ai.content.completion + + - id: gen_ai.content.prompt + name: gen_ai.content.prompt + type: event + brief: > + In the lifetime of an GenAI span, events for prompts sent and completions received + may be created, depending on the configuration of the instrumentation. + attributes: + - ref: gen_ai.prompt + requirement_level: + conditionally_required: if and only if corresponding event is enabled + note: > + It's RECOMMENDED to format prompts as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) + + - id: gen_ai.content.completion + name: gen_ai.content.completion + type: event + brief: > + In the lifetime of an GenAI span, events for prompts sent and completions received + may be created, depending on the configuration of the instrumentation. + attributes: + - ref: gen_ai.completion + requirement_level: + conditionally_required: if and only if corresponding event is enabled + note: > + It's RECOMMENDED to format completions as JSON string matching [OpenAI messages format](https://platform.openai.com/docs/guides/text-generation) diff --git a/crates/weaver_resolver/data/registry-test-4-events/registry/trace-rpc.yaml b/crates/weaver_resolver/data/registry-test-4-events/registry/trace-rpc.yaml new file mode 100644 index 00000000..d578c6ba --- /dev/null +++ b/crates/weaver_resolver/data/registry-test-4-events/registry/trace-rpc.yaml @@ -0,0 +1,131 @@ +groups: + - id: rpc + prefix: rpc + type: span + brief: 'This document defines semantic conventions for remote procedure calls.' + events: [rpc.message] + attributes: + - ref: rpc.system + requirement_level: required + - ref: rpc.service + requirement_level: recommended + - ref: rpc.method + requirement_level: recommended + - ref: network.transport + requirement_level: recommended + - ref: network.type + requirement_level: recommended + - ref: server.address + requirement_level: required + brief: > + RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + 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. + - ref: server.port + requirement_level: + conditionally_required: if the port is supported by the network transport used for communication. + + - id: rpc.client + type: span + brief: 'This document defines semantic conventions for remote procedure call client spans.' + extends: rpc + attributes: + - ref: network.peer.address + requirement_level: recommended + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + + - id: rpc.server + type: span + extends: rpc + span_kind: server + brief: 'Semantic Convention for RPC server spans' + attributes: + - ref: client.address + requirement_level: recommended + - ref: client.port + requirement_level: recommended + - ref: network.peer.address + requirement_level: recommended + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. + - ref: network.transport + requirement_level: recommended + - ref: network.type + requirement_level: recommended + + - id: rpc.grpc + type: span + extends: rpc + brief: 'Tech-specific attributes for gRPC.' + attributes: + - ref: rpc.grpc.status_code + tag: grpc-tech-specific + requirement_level: required + - ref: rpc.grpc.request.metadata + tag: grpc-tech-specific + requirement_level: opt_in + - ref: rpc.grpc.response.metadata + tag: grpc-tech-specific + requirement_level: opt_in + + - id: rpc.jsonrpc + prefix: rpc.jsonrpc + type: span + extends: rpc + brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' + attributes: + - ref: rpc.jsonrpc.version + tag: jsonrpc-tech-specific + requirement_level: + conditionally_required: If other than the default version (`1.0`) + - ref: rpc.jsonrpc.request_id + tag: jsonrpc-tech-specific + requirement_level: recommended + - ref: rpc.jsonrpc.error_code + tag: jsonrpc-tech-specific + requirement_level: + conditionally_required: If response is not successful. + - ref: rpc.jsonrpc.error_message + tag: jsonrpc-tech-specific + requirement_level: recommended + - ref: rpc.method + tag: jsonrpc-tech-specific + requirement_level: required + note: > + This is always required for jsonrpc. See the note in the general + RPC conventions for more information. + + - id: rpc.message + prefix: rpc.message + type: event + brief: "RPC received/sent message." + attributes: + - ref: rpc.message.type + requirement_level: recommended + - ref: rpc.message.id + requirement_level: recommended + - ref: rpc.message.compressed_size + requirement_level: recommended + - ref: rpc.message.uncompressed_size + requirement_level: recommended + + - id: rpc.connect_rpc + type: span + extends: rpc + brief: 'Tech-specific attributes for Connect RPC.' + attributes: + - ref: rpc.connect_rpc.error_code + tag: connect_rpc-tech-specific + requirement_level: + conditionally_required: If response is not successful and if error code available. + - ref: rpc.connect_rpc.request.metadata + tag: connect_rpc-tech-specific + requirement_level: opt_in + - ref: rpc.connect_rpc.response.metadata + tag: connect_rpc-tech-specific + requirement_level: opt_in diff --git a/crates/weaver_resolver/src/attribute.rs b/crates/weaver_resolver/src/attribute.rs index bd617df5..72a633cc 100644 --- a/crates/weaver_resolver/src/attribute.rs +++ b/crates/weaver_resolver/src/attribute.rs @@ -8,6 +8,7 @@ use serde::Deserialize; use weaver_resolved_schema::attribute; use weaver_resolved_schema::attribute::AttributeRef; +use weaver_resolved_schema::error::Error; use weaver_resolved_schema::lineage::{AttributeLineage, GroupLineage}; use weaver_semconv::attribute::AttributeSpec; @@ -23,12 +24,55 @@ pub struct AttributeCatalog { } #[derive(Debug, PartialEq)] -struct AttributeWithGroupId { +/// The Attribute with its group ID. +pub struct AttributeWithGroupId { + /// The attribute. pub attribute: attribute::Attribute, + /// The group ID. pub group_id: String, } +/// A reference to an attribute with its original attribute and group ID. +pub struct AttributeRefWithGroup { + /// The attribute reference. + pub attr_ref: AttributeRef, + /// The attribute with its group ID. + pub attr: AttributeWithGroupId, +} + impl AttributeCatalog { + /// Returns the given attribute from the catalog. + #[must_use] + pub fn get_attribute(&self, name: &str) -> Option<&AttributeWithGroupId> { + self.root_attributes.get(name) + } + + /// Returns the reference of the given attribute. + pub fn get_attribute_ref(&mut self, name: &str) -> Result { + let attr = self + .get_attribute(name) + .ok_or_else(|| Error::AttributeNotFound { + group_id: name.to_owned(), + attr_ref: AttributeRef(0), + })?; + // let group_id = attr.group_id.clone(); + let attr_ref = + self.attribute_refs + .get(&attr.attribute) + .ok_or_else(|| Error::AttributeNotFound { + group_id: attr.group_id.clone(), + attr_ref: AttributeRef(0), + })?; + + Ok(AttributeRefWithGroup { + attr_ref: *attr_ref, + attr: AttributeWithGroupId { + attribute: attr.attribute.clone(), + group_id: attr.group_id.clone(), + }, + }) + } + /// Returns the reference of the given attribute or creates a new reference if the attribute /// does not exist in the catalog. pub fn attribute_ref(&mut self, attr: attribute::Attribute) -> AttributeRef { diff --git a/crates/weaver_resolver/src/body.rs b/crates/weaver_resolver/src/body.rs new file mode 100644 index 00000000..db34bedc --- /dev/null +++ b/crates/weaver_resolver/src/body.rs @@ -0,0 +1,132 @@ +// SPDX-License-Identifier: Apache-2.0 + +//! Functions to resolve a semantic convention body. + +use weaver_resolved_schema::{ + body::{Body, BodyField}, + error::{handle_errors, Error}, +}; +use weaver_semconv::body::{BodyFieldSpec, BodySpec}; + +use crate::attribute::AttributeCatalog; + +/// Resolve a body specification into a resolved body. +pub fn resolve_body_spec( + body: &BodySpec, + attr_catalog: &mut AttributeCatalog, +) -> Result, Error> { + match body { + BodySpec::Fields { fields } => { + let mut errors = vec![]; + let mut body_fields = Vec::new(); + for field in fields.iter() { + match resolve_body_field_spec(field, attr_catalog) { + Ok(r) => body_fields.push(r), + Err(e) => errors.push(e), + } + } + handle_errors(errors)?; + Ok(Some(Body { + fields: Some(body_fields), + // value: None, // Not yet implemented + })) + } + BodySpec::Value { value: _ } => { + // Add as a placeholder for now of where to resolve the value. + Err(Error::NotImplemented { + message: "Value type for body is not currently implemented.".to_owned(), + }) + } + } +} + +/// Resolve a body field specification into a resolved body field. +pub fn resolve_body_field_spec( + field: &BodyFieldSpec, + attr_catalog: &mut AttributeCatalog, +) -> Result { + match field { + BodyFieldSpec::Ref { + r#ref, + alias, + brief, + examples, + requirement_level, + note, + stability, + deprecated, + } => { + let attr_ref = attr_catalog.get_attribute_ref(r#ref)?; + + let root_attr = attr_ref.attr.attribute.clone(); + Ok(BodyField { + name: field.id(), + r#attr: Some(attr_ref.attr_ref), + alias: alias.clone(), + r#type: root_attr.r#type.clone(), + brief: { + match brief { + Some(brief) => brief.clone(), + None => root_attr.brief.to_owned(), + } + }, + examples: { + match examples { + Some(examples) => Some(examples.to_owned()), + None => root_attr.examples.to_owned(), + } + }, + requirement_level: { + match requirement_level { + Some(level) => level.clone(), + None => root_attr.requirement_level.to_owned(), + } + }, + note: { + match note { + Some(note) => note.clone(), + None => root_attr.note.to_owned(), + } + }, + stability: { + match stability { + Some(stability) => Some(stability.to_owned()), + None => root_attr.stability.to_owned(), + } + }, + deprecated: { + match deprecated { + Some(deprecated) => Some(deprecated.to_owned()), + None => root_attr.deprecated.to_owned(), + } + }, + }) + } + BodyFieldSpec::Id { + id, + r#type, + brief, + examples, + requirement_level, + note, + stability, + deprecated, + } => Ok(BodyField { + name: id.clone(), + r#attr: None, + alias: None, + r#type: r#type.clone(), + brief: { + match brief { + Some(brief) => brief.clone(), + None => "".to_owned(), + } + }, + examples: examples.clone(), + requirement_level: requirement_level.clone(), + note: note.clone(), + stability: stability.clone(), + deprecated: deprecated.clone(), + }), + } +} diff --git a/crates/weaver_resolver/src/lib.rs b/crates/weaver_resolver/src/lib.rs index 6d8b1948..de7c0536 100644 --- a/crates/weaver_resolver/src/lib.rs +++ b/crates/weaver_resolver/src/lib.rs @@ -26,6 +26,7 @@ use crate::attribute::AttributeCatalog; use crate::registry::resolve_semconv_registry; pub mod attribute; +pub mod body; mod constraint; pub mod registry; @@ -143,6 +144,17 @@ pub enum Error { /// A container for multiple errors. #[error("{:?}", format_errors(.0))] CompoundError(Vec), + + /// An error indicating that the Body references are not resolved. + #[error("The following body reference is not resolved.\nBody reference: {group_id}\nProvenance: {provenance}\nError: {error}")] + UnresolvedBody { + /// The unresolved body reference. + group_id: String, + /// The provenance of the reference (URL or path). + provenance: String, + /// The errors that occurred. + error: String, + }, } impl WeaverError for Error { diff --git a/crates/weaver_resolver/src/registry.rs b/crates/weaver_resolver/src/registry.rs index fa7c6241..e37d17c7 100644 --- a/crates/weaver_resolver/src/registry.rs +++ b/crates/weaver_resolver/src/registry.rs @@ -8,6 +8,7 @@ use serde::Deserialize; use weaver_common::error::handle_errors; use weaver_resolved_schema::attribute::UnresolvedAttribute; +use weaver_resolved_schema::body::UnresolvedBody; use weaver_resolved_schema::lineage::{AttributeLineage, GroupLineage}; use weaver_resolved_schema::registry::{Constraint, Group, Registry}; use weaver_semconv::attribute::AttributeSpec; @@ -15,6 +16,7 @@ use weaver_semconv::group::GroupSpecWithProvenance; use weaver_semconv::registry::SemConvRegistry; use crate::attribute::AttributeCatalog; +use crate::body::resolve_body_spec; use crate::constraint::resolve_constraints; use crate::{Error, UnsatisfiedAnyOfConstraint}; @@ -42,6 +44,9 @@ pub struct UnresolvedGroup { /// and other signals, into the group field once they are resolved. pub attributes: Vec, + /// The unresolved body that belongs to this group + pub body: Option, + /// The provenance of the group (URL or path). pub provenance: String, } @@ -82,6 +87,8 @@ pub fn resolve_semconv_registry( resolve_include_constraints(&mut ureg)?; + resolve_body(&mut ureg, attr_catalog)?; + // Sort the attribute internal references in each group. // This is needed to ensure that the resolved registry is easy to compare // in unit tests. @@ -265,8 +272,10 @@ fn group_from_spec(group: GroupSpecWithProvenance) -> UnresolvedGroup { name: group.spec.name, lineage: Some(GroupLineage::new(&group.provenance)), display_name: group.spec.display_name, + body: None, // The body is resolved and populated later. }, attributes: attrs, + body: { group.spec.body.map(|body| UnresolvedBody { spec: body }) }, provenance: group.provenance, } } @@ -685,6 +694,40 @@ fn resolve_inheritance_attr( } } +fn resolve_body( + ureg: &mut UnresolvedRegistry, + attr_catalog: &mut AttributeCatalog, +) -> Result<(), Error> { + let mut errors = vec![]; + + for unresolved_group in ureg.groups.iter_mut() { + let body = &unresolved_group.body; + match body { + Some(body) => { + let resolved_body = resolve_body_spec(&body.spec, attr_catalog); + match resolved_body { + Ok(resolved_body) => { + unresolved_group.group.body = resolved_body; + } + Err(e) => { + errors.push(Error::UnresolvedBody { + group_id: unresolved_group.group.id.clone(), + provenance: unresolved_group.provenance.clone(), + error: e.to_string(), + }); + } + } + } + None => { + // No body to resolve. + } + } + } + + handle_errors(errors)?; + Ok(()) +} + #[cfg(test)] mod tests { use std::collections::HashSet; diff --git a/crates/weaver_semconv/data/event.yaml b/crates/weaver_semconv/data/event.yaml new file mode 100644 index 00000000..241f88b7 --- /dev/null +++ b/crates/weaver_semconv/data/event.yaml @@ -0,0 +1,149 @@ +groups: + - id: device.app.lifecycle + stability: experimental + type: event + name: device.app.lifecycle + brief: > + This event represents an occurrence of a lifecycle transition on Android or iOS platform. + note: > + This event identifies the fields that are common to all lifecycle events for android and iOS using + the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are + mutually exclusive. + body: + fields: + - id: ios.state + stability: experimental + requirement_level: + conditionally_required: if and only if `os.name` is `ios` + note: > + The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), + and from which the `OS terminology` column values are derived. + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + type: + allow_custom_values: false + members: + - id: active + value: 'active' + brief: > + The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + - id: inactive + value: 'inactive' + brief: > + The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + - id: background + value: 'background' + brief: > + The app is now in the background. + This value is associated with UIKit notification `applicationDidEnterBackground`. + - id: foreground + value: 'foreground' + brief: > + The app is now in the foreground. + This value is associated with UIKit notification `applicationWillEnterForeground`. + - id: terminate + value: 'terminate' + brief: > + The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + - id: android.state + stability: experimental + requirement_level: + conditionally_required: if and only if `os.name` is `android` + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + note: > + The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), + and from which the `OS identifiers` are derived. + type: + allow_custom_values: false + members: + - id: created + value: 'created' + brief: > + Any time before Activity.onResume() or, if the app has no Activity, Context.startService() + has been called in the app for the first time. + - id: background + value: 'background' + brief: > + Any time after Activity.onPause() or, if the app has no Activity, + Context.stopService() has been called when the app was in the foreground state. + - id: foreground + value: 'foreground' + brief: > + Any time after Activity.onResume() or, if the app has no Activity, + Context.startService() has been called when the app was in either the created or background states. + + - id: span.event.test.no_name + stability: experimental + type: event + prefix: span.event.test + brief: > + This event represents an occurrence of a span event. + attributes: + - id: attribute1 + type: string + brief: 'The attribute1' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `attribute2` is not set, recommended otherwise. + - id: attribute2 + type: string + brief: 'The attribute2' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `attribute1` is not set, recommended otherwise. + + - id: span.event.test.with_name + name: span.event.test.with_name + stability: experimental + type: event + prefix: span.event.test.with_name + brief: > + This event represents an occurrence of a span event. + attributes: + - id: attribute1 + type: string + brief: 'The attribute1' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `attribute2` is not set, recommended otherwise. + - id: attribute2 + type: string + brief: 'The attribute2' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `attribute1` is not set, recommended otherwise. + + - id: test.event.with_attributes + name: test.event.with_attributes + stability: experimental + type: event + brief: > + This event represents an occurrence of a test event. + attributes: + - id: attribute1 + type: string + brief: 'The attribute1' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `attribute2` is not set, recommended otherwise. + - id: attribute2 + type: string + brief: 'The attribute2' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `attribute1` is not set, recommended otherwise. + body: + fields: + - id: field1 + type: string + brief: 'The field1' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `field2` is not set, recommended otherwise. + - id: field2 + type: string + brief: 'The field2' + examples: ['value1', 'value2'] + requirement_level: + conditionally_required: Required if `field1` is not set, recommended otherwise. \ No newline at end of file diff --git a/crates/weaver_semconv/src/body.rs b/crates/weaver_semconv/src/body.rs new file mode 100644 index 00000000..bb44b269 --- /dev/null +++ b/crates/weaver_semconv/src/body.rs @@ -0,0 +1,404 @@ +// SPDX-License-Identifier: Apache-2.0 + +#![allow(rustdoc::invalid_html_tags)] + +//! Body Field specification. + +use serde::{Deserialize, Serialize}; + +use crate::attribute::{ + AttributeType, BasicRequirementLevelSpec, Examples, RequirementLevel, ValueSpec, +}; +use crate::stability::Stability; + +/// A body specification +#[derive(Serialize, Deserialize, Debug, Clone)] +#[serde(deny_unknown_fields)] +#[serde(untagged)] +#[serde(rename_all = "snake_case")] +pub enum BodySpec { + /// The collection of body fields associated with a body definition + Fields { + /// The collection of body fields associated with a body definition + #[serde(skip_serializing_if = "Vec::is_empty")] + fields: Vec, + }, + /// The body field value. + Value { + /// The body field value. + value: ValueSpec, + }, +} + +impl BodySpec { + /// Returns true if the body field is required. + #[must_use] + pub fn has_fields(&self) -> bool { + match self { + BodySpec::Fields { fields } => !fields.is_empty(), + BodySpec::Value { value: _ } => false, + } + } +} + +/// A body field specification. +#[derive(Serialize, Deserialize, Debug, Clone)] +#[serde(deny_unknown_fields)] +#[serde(untagged)] +#[serde(rename_all = "snake_case")] +pub enum BodyFieldSpec { + /// Reference to an attribute. + /// + /// ref MUST have an id of an existing attribute. + Ref { + /// Reference an existing attribute. + r#ref: String, + /// The alias to use for the referenced attribute in this body field, + /// if not specified, the id of the referenced attribute is used. + #[serde(skip_serializing_if = "Option::is_none")] + alias: Option, + /// A brief description of the attribute. + #[serde(skip_serializing_if = "Option::is_none")] + brief: Option, + /// Sequence of example values for the attribute or single example + /// value. They are required only for string and string array + /// attributes. Example values must be of the same type of the + /// attribute. If only a single example is provided, it can directly + /// be reported without encapsulating it into a sequence/dictionary. + #[serde(skip_serializing_if = "Option::is_none")] + examples: Option, + /// Specifies if the attribute is mandatory. Can be "required", + /// "conditionally_required", "recommended" or "opt_in". When omitted, + /// the attribute is "recommended". When set to + /// "conditionally_required", the string provided as MUST + /// specify the conditions under which the attribute is required. + #[serde(skip_serializing_if = "Option::is_none")] + requirement_level: Option, + /// A more elaborate description of the attribute. + /// It defaults to an empty string. + #[serde(default)] + #[serde(skip_serializing_if = "Option::is_none")] + note: Option, + /// Specifies the stability of the attribute. + /// Note that, if stability is missing but deprecated is present, it will + /// automatically set the stability to deprecated. If deprecated is + /// present and stability differs from deprecated, this will result in an + /// error. + #[serde(skip_serializing_if = "Option::is_none")] + stability: Option, + /// Specifies if the attribute is deprecated. The string + /// provided as MUST specify why it's deprecated and/or what + /// to use instead. See also stability. + #[serde(skip_serializing_if = "Option::is_none")] + deprecated: Option, + }, + /// Body Field definition. + Id { + /// String that uniquely identifies the body field. + id: String, + /// Either a string literal denoting the type as a primitive or an + /// array type, a template type or an enum definition. + r#type: AttributeType, + /// A brief description of the body field. + brief: Option, + /// Sequence of example values for the body field or single example + /// value. They are required only for string and string array + /// attributes. Example values must be of the same type of the + /// body field. If only a single example is provided, it can directly + /// be reported without encapsulating it into a sequence/dictionary. + #[serde(skip_serializing_if = "Option::is_none")] + examples: Option, + /// Specifies if the body field is mandatory. Can be "required", + /// "conditionally_required", "recommended" or "opt_in". When omitted, + /// the body field is "recommended". When set to + /// "conditionally_required", the string provided as MUST + /// specify the conditions under which the body field is required. + #[serde(default)] + requirement_level: RequirementLevel, + /// A more elaborate description of the body field. + /// It defaults to an empty string. + #[serde(default)] + note: String, + /// Specifies the stability of the body field. + /// Note that, if stability is missing but deprecated is present, it will + /// automatically set the stability to deprecated. If deprecated is + /// present and stability differs from deprecated, this will result in an + /// error. + #[serde(skip_serializing_if = "Option::is_none")] + stability: Option, + /// Specifies if the body field is deprecated. The string + /// provided as MUST specify why it's deprecated and/or what + /// to use instead. See also stability. + #[serde(skip_serializing_if = "Option::is_none")] + deprecated: Option, + }, +} + +impl BodyFieldSpec { + /// Returns true if the body field is required. + #[must_use] + pub fn is_required(&self) -> bool { + matches!( + self, + BodyFieldSpec::Id { + requirement_level: RequirementLevel::Basic(BasicRequirementLevelSpec::Required), + .. + } | BodyFieldSpec::Ref { + requirement_level: Some(RequirementLevel::Basic( + BasicRequirementLevelSpec::Required + )), + .. + } + ) + } + + /// Returns the id of the body field. + #[must_use] + pub fn id(&self) -> String { + match self { + BodyFieldSpec::Ref { r#ref, alias, .. } => { + if alias.is_some() { + alias.clone().unwrap_or_default() + } else { + r#ref.clone() + } + } + BodyFieldSpec::Id { id, .. } => id.clone(), + } + } + + /// Returns the brief of the body field. + #[must_use] + pub fn brief(&self) -> String { + match self { + BodyFieldSpec::Ref { brief, .. } => brief.clone().unwrap_or_default(), + BodyFieldSpec::Id { brief, .. } => brief.clone().unwrap_or_default(), + } + } + + /// Returns the note of the body field. + #[must_use] + pub fn note(&self) -> String { + match self { + BodyFieldSpec::Ref { note, .. } => note.clone().unwrap_or_default(), + BodyFieldSpec::Id { note, .. } => note.clone(), + } + } +} + +// /// The different types of body fields (specification). +// #[derive(Serialize, Deserialize, Debug, Clone, Eq, PartialEq, Hash, JsonSchema)] +// #[serde(rename_all = "snake_case")] +// #[serde(untagged)] +// pub enum BodyFieldType { +// /// Primitive or array type. +// PrimitiveOrArray(PrimitiveOrArrayTypeSpec), +// /// A template type. +// Template(TemplateTypeSpec), +// /// An enum definition type. +// Enum { +// /// Set to false to not accept values other than the specified members. +// /// It defaults to true. +// #[serde(default = "default_as_true")] +// allow_custom_values: bool, +// /// List of enum entries. +// members: Vec, +// }, +// } + +/// Implements a human readable display for BodyFieldType. +// impl Display for BodyFieldType { +// fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { +// match self { +// BodyFieldType::PrimitiveOrArray(t) => write!(f, "{}", t), +// BodyFieldType::Template(t) => write!(f, "{}", t), +// BodyFieldType::Enum { members, .. } => { +// let entries = members +// .iter() +// .map(|m| m.id.clone()) +// .collect::>() +// .join(", "); +// write!(f, "enum {{{}}}", entries) +// } +// } +// } +// } + +/// Specifies the default value for allow_custom_values. +// fn default_as_true() -> bool { +// true +// } + +#[cfg(test)] +mod tests { + use super::*; + use crate::attribute::{ + EnumEntriesSpec, PrimitiveOrArrayTypeSpec, TemplateTypeSpec, ValueSpec, + }; + + #[test] + fn test_body_field_type_display() { + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Boolean) + ), + "boolean" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Int) + ), + "int" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Double) + ), + "double" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::String) + ), + "string" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Strings) + ), + "string[]" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Ints) + ), + "int[]" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Doubles) + ), + "double[]" + ); + assert_eq!( + format!( + "{}", + AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Booleans) + ), + "boolean[]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Boolean)), + "template[boolean]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Int)), + "template[int]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Double)), + "template[double]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::String)), + "template[string]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Strings)), + "template[string[]]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Ints)), + "template[int[]]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Doubles)), + "template[double[]]" + ); + assert_eq!( + format!("{}", AttributeType::Template(TemplateTypeSpec::Booleans)), + "template[boolean[]]" + ); + assert_eq!( + format!( + "{}", + AttributeType::Enum { + allow_custom_values: true, + members: vec![EnumEntriesSpec { + id: "id".to_owned(), + value: ValueSpec::Int(42), + brief: Some("brief".to_owned()), + note: Some("note".to_owned()), + stability: None, + deprecated: None, + }] + } + ), + "enum {id}" + ); + } + + #[test] + fn test_body_field() { + let attr = BodyFieldSpec::Id { + id: "id".to_owned(), + r#type: AttributeType::PrimitiveOrArray(PrimitiveOrArrayTypeSpec::Int), + brief: Some("brief".to_owned()), + examples: Some(Examples::Int(42)), + requirement_level: RequirementLevel::Basic(BasicRequirementLevelSpec::Required), + note: "note".to_owned(), + stability: Some(Stability::Stable), + deprecated: Some("deprecated".to_owned()), + }; + assert_eq!(attr.id(), "id"); + assert_eq!(attr.brief(), "brief"); + assert_eq!(attr.note(), "note"); + assert!(attr.is_required()); + + let attr = BodyFieldSpec::Ref { + r#ref: "ref".to_owned(), + alias: None, + brief: Some("brief".to_owned()), + examples: Some(Examples::Int(42)), + requirement_level: Some(RequirementLevel::Basic(BasicRequirementLevelSpec::Required)), + note: Some("note".to_owned()), + stability: Some(Stability::Stable), + deprecated: Some("deprecated".to_owned()), + }; + assert_eq!(attr.id(), "ref"); + assert_eq!(attr.brief(), "brief"); + assert_eq!(attr.note(), "note"); + assert!(attr.is_required()); + + let attr = BodyFieldSpec::Ref { + r#ref: "ref".to_owned(), + alias: Some("theAlias".to_owned()), + brief: Some("brief".to_owned()), + examples: Some(Examples::Int(42)), + requirement_level: Some(RequirementLevel::Basic(BasicRequirementLevelSpec::Required)), + note: Some("note".to_owned()), + stability: Some(Stability::Stable), + deprecated: Some("deprecated".to_owned()), + }; + assert_eq!(attr.id(), "theAlias"); + assert_eq!(attr.brief(), "brief"); + assert_eq!(attr.note(), "note"); + assert!(attr.is_required()); + } +} + +/// An attribute definition with its provenance (path or URL). +#[derive(Debug, Clone)] +pub struct BodyFieldSpecWithProvenance { + /// The body field definition. + pub body_field: BodyFieldSpec, + /// The provenance of the body field (path or URL). + pub provenance: String, +} diff --git a/crates/weaver_semconv/src/group.rs b/crates/weaver_semconv/src/group.rs index e2e5e2c7..2e592bce 100644 --- a/crates/weaver_semconv/src/group.rs +++ b/crates/weaver_semconv/src/group.rs @@ -10,6 +10,7 @@ use std::fmt::{Display, Formatter}; use serde::{Deserialize, Serialize}; use crate::attribute::{AttributeSpec, AttributeType, PrimitiveOrArrayTypeSpec}; +use crate::body::BodySpec; use crate::group::InstrumentSpec::{Counter, Gauge, Histogram, UpDownCounter}; use crate::stability::Stability; use crate::Error; @@ -86,6 +87,9 @@ pub struct GroupSpec { pub name: Option, /// The readable name for attribute groups used when generating registry tables. pub display_name: Option, + /// The event body definition + /// Note: only valid if type is event + pub body: Option, } impl GroupSpec { @@ -114,11 +118,30 @@ impl GroupSpec { } // Field name is required if prefix is empty and if type is event. - if self.r#type == GroupType::Event && self.prefix.is_empty() && self.name.is_none() { + if self.r#type == GroupType::Event { + if self.body.is_some() && self.name.is_none() { + // Must have a name which is assigned to event.name for log based events + errors.push(Error::InvalidGroup { + path_or_url: path_or_url.to_owned(), + group_id: self.id.clone(), + error: "This group contains an event type with a body definition but the name is not set.".to_owned(), + }); + } + if self.name.is_none() && self.prefix.is_empty() { + // Must have a name (whether explicit or via a prefix which will derive the name) + errors.push(Error::InvalidGroup { + path_or_url: path_or_url.to_owned(), + group_id: self.id.clone(), + error: "This group contains an event type but the name is not set and no prefix is defined.".to_owned(), + }); + } + } else if self.body.is_some() { + // Make sure that body is only used for events errors.push(Error::InvalidGroup { path_or_url: path_or_url.to_owned(), group_id: self.id.clone(), - error: "This group contains an event type but the prefix is empty and the name is not set.".to_owned(), + error: "This group contains a body field but the type is not set to event." + .to_owned(), }); } @@ -334,6 +357,7 @@ mod tests { unit: None, name: None, display_name: None, + body: None, }; assert!(group.validate("").is_ok()); @@ -396,7 +420,7 @@ mod tests { InvalidGroup { path_or_url: "".to_owned(), group_id: "test".to_owned(), - error: "This group contains an event type but the prefix is empty and the name is not set.".to_owned(), + error: "This group contains an event type but the name is not set and no prefix is defined.".to_owned(), }, ], ), @@ -434,6 +458,7 @@ mod tests { unit: None, name: None, display_name: None, + body: None, }; assert!(group.validate("").is_ok()); diff --git a/crates/weaver_semconv/src/lib.rs b/crates/weaver_semconv/src/lib.rs index 4b52ae4d..588ea114 100644 --- a/crates/weaver_semconv/src/lib.rs +++ b/crates/weaver_semconv/src/lib.rs @@ -9,6 +9,7 @@ use weaver_common::diagnostic::{DiagnosticMessage, DiagnosticMessages}; use weaver_common::error::{format_errors, WeaverError}; pub mod attribute; +pub mod body; pub mod group; pub mod metric; pub mod path; @@ -139,6 +140,7 @@ mod tests { "data/cloudevents.yaml", "data/database.yaml", "data/database-metrics.yaml", + "data/event.yaml", "data/exception.yaml", "data/faas.yaml", "data/faas-common.yaml", diff --git a/crates/weaver_semconv/src/registry.rs b/crates/weaver_semconv/src/registry.rs index 651aa4ae..83699794 100644 --- a/crates/weaver_semconv/src/registry.rs +++ b/crates/weaver_semconv/src/registry.rs @@ -261,6 +261,7 @@ mod tests { events: vec![], name: None, display_name: Some("Group 1".to_owned()), + body: None, }], }, ), @@ -285,6 +286,7 @@ mod tests { events: vec![], name: None, display_name: Some("Group 2".to_owned()), + body: None, }], }, ),