diff --git a/.chloggen/1646.yaml b/.chloggen/1646.yaml new file mode 100644 index 000000000..d043e5b65 --- /dev/null +++ b/.chloggen/1646.yaml @@ -0,0 +1,5 @@ +change_type: breaking +component: code +note: "`code.function.name` value should contain the fully qualified function name, `code.namespace` is now deprecated" +issues: [1677] +subtext: diff --git a/docs/attributes-registry/code.md b/docs/attributes-registry/code.md index 5e71ba718..f2f72c32b 100644 --- a/docs/attributes-registry/code.md +++ b/docs/attributes-registry/code.md @@ -14,11 +14,26 @@ These attributes provide context about source code |---|---|---|---|---| | `code.column.number` | int | The column number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. | `16` | ![Development](https://img.shields.io/badge/-development-blue) | | `code.file.path` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | ![Development](https://img.shields.io/badge/-development-blue) | -| `code.function.name` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | ![Development](https://img.shields.io/badge/-development-blue) | +| `code.function.name` | string | The method or function fully-qualified name without arguments. The value should fit the natural representation of the language runtime, which is also likely the same used within `code.stacktrace` attribute value. [1] | `com.example.MyHttpService.serveRequest`; `GuzzleHttp\Client::transfer`; `fopen` | ![Development](https://img.shields.io/badge/-development-blue) | | `code.line.number` | int | The line number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. | `42` | ![Development](https://img.shields.io/badge/-development-blue) | -| `code.namespace` | string | The "namespace" within which `code.function.name` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function.name` form a unique identifier for the code unit. | `com.example.MyHttpService` | ![Development](https://img.shields.io/badge/-development-blue) | | `code.stacktrace` | string | 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. | `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)` | ![Development](https://img.shields.io/badge/-development-blue) | +**[1] `code.function.name`:** Values and format depends on each language runtime, thus it is impossible to provide an exhaustive list of examples. +The values are usually the same (or prefixes of) the ones found in native stack trace representation stored in +`code.stacktrace` without information on arguments. + +Examples: + +* Java method: `com.example.MyHttpService.serveRequest` +* Java anonymous class method: `com.mycompany.Main$1.myMethod` +* Java lambda method: `com.mycompany.Main$$Lambda/0x0000748ae4149c00.myMethod` +* PHP function: `GuzzleHttp\Client::transfer +* Go function: `github.com/my/repo/pkg.foo.func5` +* Elixir: `OpenTelemetry.Ctx.new` +* Erlang: `opentelemetry_ctx:new` +* Rust: `playground::my_module::my_cool_func` +* C function: `fopen` + ## Deprecated Code Attributes These deprecated attributes provide context about source code @@ -26,6 +41,7 @@ These deprecated attributes provide context about source code | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `code.column` | int | Deprecated, use `code.column.number` | `16` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `code.column.number` | -| `code.filepath` | string | Deprecated, use `code.file.path` instead | `/usr/local/MyApplication/content_root/app/index.php` | ![Development](https://img.shields.io/badge/-development-blue) | +| `code.filepath` | string | Deprecated, use `code.file.path` instead | `/usr/local/MyApplication/content_root/app/index.php` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `code.file.path` | | `code.function` | string | Deprecated, use `code.function.name` instead | `serveRequest` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `code.function.name` | | `code.lineno` | int | Deprecated, use `code.line.number` instead | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `code.line.number` | +| `code.namespace` | string | Deprecated, namespace is now included into `code.function.name` | `com.example.MyHttpService` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `code.function.name` which is expected to be a fully-qualified name. | diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 443ee21ec..40348ee28 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -431,12 +431,28 @@ about the span. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`code.column.number`](/docs/attributes-registry/code.md) | int | The column number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. | `16` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`code.filepath`](/docs/attributes-registry/code.md) | string | Deprecated, use `code.file.path` instead | `/usr/local/MyApplication/content_root/app/index.php` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`code.function.name`](/docs/attributes-registry/code.md) | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`code.filepath`](/docs/attributes-registry/code.md) | string | Deprecated, use `code.file.path` instead | `/usr/local/MyApplication/content_root/app/index.php` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `code.file.path` | +| [`code.function.name`](/docs/attributes-registry/code.md) | string | The method or function fully-qualified name without arguments. The value should fit the natural representation of the language runtime, which is also likely the same used within `code.stacktrace` attribute value. [1] | `com.example.MyHttpService.serveRequest`; `GuzzleHttp\Client::transfer`; `fopen` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`code.line.number`](/docs/attributes-registry/code.md) | int | The line number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. | `42` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`code.namespace`](/docs/attributes-registry/code.md) | string | The "namespace" within which `code.function.name` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function.name` form a unique identifier for the code unit. | `com.example.MyHttpService` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`code.namespace`](/docs/attributes-registry/code.md) | string | Deprecated, namespace is now included into `code.function.name` | `com.example.MyHttpService` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Value should be included in `code.function.name` which is expected to be a fully-qualified name. | | [`code.stacktrace`](/docs/attributes-registry/code.md) | string | 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. | `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)` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +**[1] `code.function.name`:** Values and format depends on each language runtime, thus it is impossible to provide an exhaustive list of examples. +The values are usually the same (or prefixes of) the ones found in native stack trace representation stored in +`code.stacktrace` without information on arguments. + +Examples: + +* Java method: `com.example.MyHttpService.serveRequest` +* Java anonymous class method: `com.mycompany.Main$1.myMethod` +* Java lambda method: `com.mycompany.Main$$Lambda/0x0000748ae4149c00.myMethod` +* PHP function: `GuzzleHttp\Client::transfer +* Go function: `github.com/my/repo/pkg.foo.func5` +* Elixir: `OpenTelemetry.Ctx.new` +* Erlang: `opentelemetry_ctx:new` +* Rust: `playground::my_module::my_cool_func` +* C function: `fopen` + diff --git a/model/code/registry-deprecated.yaml b/model/code/registry-deprecated.yaml index a345b7702..de655f884 100644 --- a/model/code/registry-deprecated.yaml +++ b/model/code/registry-deprecated.yaml @@ -15,6 +15,7 @@ groups: - id: code.filepath type: string stability: development + deprecated: Replaced by `code.file.path` brief: > Deprecated, use `code.file.path` instead examples: /usr/local/MyApplication/content_root/app/index.php @@ -32,3 +33,10 @@ groups: brief: > Deprecated, use `code.column.number` examples: 16 + - id: code.namespace + type: string + stability: development + deprecated: Value should be included in `code.function.name` which is expected to be a fully-qualified name. + brief: > + Deprecated, namespace is now included into `code.function.name` + examples: com.example.MyHttpService diff --git a/model/code/registry.yaml b/model/code/registry.yaml index 4806fbb41..24f0fcfa1 100644 --- a/model/code/registry.yaml +++ b/model/code/registry.yaml @@ -9,15 +9,28 @@ groups: type: string stability: development brief: > - The method or function name, or equivalent (usually rightmost part of the code unit's name). - examples: serveRequest - - id: code.namespace - type: string - stability: development - brief: > - The "namespace" within which `code.function.name` is defined. Usually the qualified class or module name, - such that `code.namespace` + some separator + `code.function.name` form a unique identifier for the code unit. - examples: com.example.MyHttpService + The method or function fully-qualified name without arguments. The value should fit the natural representation of the language + runtime, which is also likely the same used within `code.stacktrace` attribute value. + examples: + - 'com.example.MyHttpService.serveRequest' + - 'GuzzleHttp\Client::transfer' + - 'fopen' + note: | + Values and format depends on each language runtime, thus it is impossible to provide an exhaustive list of examples. + The values are usually the same (or prefixes of) the ones found in native stack trace representation stored in + `code.stacktrace` without information on arguments. + + Examples: + + * Java method: `com.example.MyHttpService.serveRequest` + * Java anonymous class method: `com.mycompany.Main$1.myMethod` + * Java lambda method: `com.mycompany.Main$$Lambda/0x0000748ae4149c00.myMethod` + * PHP function: `GuzzleHttp\Client::transfer + * Go function: `github.com/my/repo/pkg.foo.func5` + * Elixir: `OpenTelemetry.Ctx.new` + * Erlang: `opentelemetry_ctx:new` + * Rust: `playground::my_module::my_cool_func` + * C function: `fopen` - id: code.file.path type: string stability: development