Adapt Elasticsearch spec to stability changes (#1002)
Co-authored-by: Steve Rao <raozihao.rzh@alibaba-inc.com> Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
This commit is contained in:
Gergely Kalapos
GitHub
parent
de58491fa5
commit
315a717762
|
|
@ -0,0 +1,24 @@
|
|||
# Use this changelog template to create an entry for release notes.
|
||||
#
|
||||
# If your change doesn't affect end users you should instead start
|
||||
# your pull request title with [chore] or use the "Skip Changelog" label.
|
||||
|
||||
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
|
||||
change_type: breaking
|
||||
|
||||
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
|
||||
component: db
|
||||
|
||||
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
|
||||
note: >
|
||||
Align Elasticsearch span name to the general database span name guidelines.
|
||||
Deprecates `db.elasticsearch.cluster.name` in favor of `db.namespace`.
|
||||
|
||||
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
|
||||
# The values here must be integers.
|
||||
issues: [1002]
|
||||
|
||||
# (Optional) One or more lines of additional information to render under the primary note.
|
||||
# These lines will be padded with 2 spaces and then inserted directly into the document.
|
||||
# Use pipe (|) for multiline entries.
|
||||
subtext:
|
||||
|
|
@ -189,21 +189,22 @@ This group defines attributes for Azure Cosmos DB.
|
|||
|
||||
"Describes deprecated db attributes."
|
||||
|
||||
| Attribute | Type | Description | Examples | Stability |
|
||||
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `db.cassandra.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.connection_string` | string | Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | <br>"Replaced by `server.address` and `server.port`." |
|
||||
| `db.cosmosdb.container` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.instance.id` | string | Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | `mysql-e26b99z.example.com` | <br>Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. |
|
||||
| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | <br>Removed as not used. |
|
||||
| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | <br>Deprecated, no replacement at this time. |
|
||||
| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | <br>Replaced by `db.namespace`. |
|
||||
| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | <br>Replaced by `db.operation.name`. |
|
||||
| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | <br>Replaced by `db.namespace`. |
|
||||
| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | <br>Replaced by `db.query.text`. |
|
||||
| `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | <br>No replacement at this time. |
|
||||
| Attribute | Type | Description | Examples | Stability |
|
||||
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `db.cassandra.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.connection_string` | string | Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | <br>"Replaced by `server.address` and `server.port`." |
|
||||
| `db.cosmosdb.container` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.elasticsearch.cluster.name` | string | Deprecated, use `db.namespace` instead. | `e9106fc68e3044f0b1475b04bf4ffd5f` | <br>Replaced by `db.namespace`. |
|
||||
| `db.instance.id` | string | Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. | `mysql-e26b99z.example.com` | <br>Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead. |
|
||||
| `db.jdbc.driver_classname` | string | Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | <br>Removed as not used. |
|
||||
| `db.mongodb.collection` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.mssql.instance_name` | string | Deprecated, SQL Server instance is now populated as a part of `db.namespace` attribute. | `MSSQLSERVER` | <br>Deprecated, no replacement at this time. |
|
||||
| `db.name` | string | Deprecated, use `db.namespace` instead. | `customers`; `main` | <br>Replaced by `db.namespace`. |
|
||||
| `db.operation` | string | Deprecated, use `db.operation.name` instead. | `findAndModify`; `HMSET`; `SELECT` | <br>Replaced by `db.operation.name`. |
|
||||
| `db.redis.database_index` | int | Deprecated, use `db.namespace` instead. | `0`; `1`; `15` | <br>Replaced by `db.namespace`. |
|
||||
| `db.sql.table` | string | Deprecated, use `db.collection.name` instead. | `mytable` | <br>Replaced by `db.collection.name`. |
|
||||
| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | <br>Replaced by `db.query.text`. |
|
||||
| `db.user` | string | Deprecated, no replacement at this time. | `readonly_user`; `reporting_user` | <br>No replacement at this time. |
|
||||
|
||||
## Db Elasticsearch Attributes
|
||||
|
||||
|
|
@ -211,7 +212,6 @@ This group defines attributes for Elasticsearch.
|
|||
|
||||
| Attribute | Type | Description | Examples | Stability |
|
||||
| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` |  |
|
||||
| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` |  |
|
||||
| `db.elasticsearch.path_parts.<key>` | string | A dynamic value in the url path. [8] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` |  |
|
||||
|
||||
|
|
|
|||
|
|
@ -14,12 +14,7 @@ described on this page.
|
|||
|
||||
## Span Name
|
||||
|
||||
The **span name** SHOULD be of the format `<endpoint id>`.
|
||||
|
||||
The elasticsearch endpoint identifier is used instead of the url path in order to reduce the cardinality of the span
|
||||
name, as the path could contain dynamic values. The endpoint id is the `name` field in the
|
||||
[elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json).
|
||||
If the endpoint id is not available, the span name SHOULD be the `http.request.method`.
|
||||
The **span name** follows the [general database span name guidelines](database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`.
|
||||
|
||||
## Attributes
|
||||
|
||||
|
|
@ -38,12 +33,13 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m
|
|||
| [`db.elasticsearch.path_parts.<key>`](/docs/attributes-registry/db.md) | string | A dynamic value in the url path. [4] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | `Conditionally Required` when the url has dynamic values |  |
|
||||
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] |  |
|
||||
| [`db.elasticsearch.cluster.name`](/docs/attributes-registry/db.md) | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | `Recommended` [8] |  |
|
||||
| [`db.elasticsearch.node.name`](/docs/attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | `Recommended` [9] |  |
|
||||
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [10] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [11] |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`db.collection.name`](/docs/attributes-registry/db.md) | string | The index or data stream against which the query is executed. [8] | `my_index`; `index1, index2` | `Recommended` |  |
|
||||
| [`db.elasticsearch.node.name`](/docs/attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. [9] | `instance-0000000001` | `Recommended` |  |
|
||||
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the Elasticsearch cluster which the client connects to. [10] | `customers`; `test.users` | `Recommended` |  |
|
||||
| [`db.query.text`](/docs/attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. [11] | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | `Recommended` [12] |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [13] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
||||
**[1]:** This SHOULD be the endpoint identifier for the request.
|
||||
**[1]:** The `db.operation.name` SHOULD match the endpoint identifier provided in the request (see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)).
|
||||
|
||||
**[2]:** 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)
|
||||
|
|
@ -72,15 +68,17 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
|
|||
|
||||
**[7]:** If using a port other than the default port for this DBMS and if `server.address` is set.
|
||||
|
||||
**[8]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
|
||||
**[8]:** The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those. If the query doesn't target a specific index, this field MUST NOT be set.
|
||||
|
||||
**[9]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
|
||||
|
||||
**[10]:** For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
|
||||
**[10]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
|
||||
|
||||
**[11]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.
|
||||
**[11]:** For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable.
|
||||
|
||||
**[12]:** 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.
|
||||
**[12]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information.
|
||||
|
||||
**[13]:** 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.
|
||||
|
||||
|
||||
|
||||
|
|
@ -117,16 +115,17 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
|
|||
|
||||
| Key | Value |
|
||||
|:------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Span name | `"search"` |
|
||||
| Span name | `"search my-index"` |
|
||||
| `db.system` | `"elasticsearch"` |
|
||||
| `server.address` | `"elasticsearch.mydomain.com"` |
|
||||
| `server.port` | `9200` |
|
||||
| `http.request.method` | `"GET"` |
|
||||
| `db.query.text` | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` |
|
||||
| `db.operation.name` | `"search"` |
|
||||
| `db.collection.name` | `"my-index"` |
|
||||
| `url.full` | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"` |
|
||||
| `db.elasticsearch.path_parts.index` | `"my-index-000001"` |
|
||||
| `db.elasticsearch.cluster.name` | `"e9106fc68e3044f0b1475b04bf4ffd5f"` |
|
||||
| `db.instance.id` | `"instance-0000000001"` |
|
||||
| `db.namespace` | `"my-cluster"` |
|
||||
| `db.elasticsearch.node.name` | `"instance-0000000001"` |
|
||||
|
||||
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|
||||
|
|
|
|||
|
|
@ -497,12 +497,6 @@ groups:
|
|||
brief: >
|
||||
This group defines attributes for Elasticsearch.
|
||||
attributes:
|
||||
- id: elasticsearch.cluster.name
|
||||
type: string
|
||||
stability: experimental
|
||||
brief: >
|
||||
Represents the identifier of an Elasticsearch cluster.
|
||||
examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"]
|
||||
- id: elasticsearch.node.name
|
||||
type: string
|
||||
stability: experimental
|
||||
|
|
|
|||
|
|
@ -84,6 +84,13 @@ groups:
|
|||
brief: 'Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead.'
|
||||
deprecated: 'Deprecated, no general replacement at this time. For Elasticsearch, use `db.elasticsearch.node.name` instead.'
|
||||
examples: 'mysql-e26b99z.example.com'
|
||||
- id: elasticsearch.cluster.name
|
||||
type: string
|
||||
stability: experimental
|
||||
deprecated: Replaced by `db.namespace`.
|
||||
brief: >
|
||||
Deprecated, use `db.namespace` instead.
|
||||
examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"]
|
||||
|
||||
- id: registry.db.metrics.deprecated
|
||||
type: attribute_group
|
||||
|
|
|
|||
|
|
@ -226,7 +226,9 @@ groups:
|
|||
requirement_level: required
|
||||
- ref: db.operation.name
|
||||
requirement_level: required
|
||||
note: This SHOULD be the endpoint identifier for the request.
|
||||
note: >
|
||||
The `db.operation.name` SHOULD match the endpoint identifier provided in the request
|
||||
(see the [Elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json)).
|
||||
examples: [ 'search', 'ml.close_job', 'cat.aliases' ]
|
||||
- ref: url.full
|
||||
requirement_level: required
|
||||
|
|
@ -238,16 +240,24 @@ groups:
|
|||
sensitive information.
|
||||
brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string.
|
||||
examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ]
|
||||
- ref: db.collection.name
|
||||
requirement_level: recommended
|
||||
brief: The index or data stream against which the query is executed.
|
||||
note: >
|
||||
The query may target multiple indices or data streams, in which case it SHOULD be a comma separated list of those.
|
||||
If the query doesn't target a specific index, this field MUST NOT be set.
|
||||
examples: [ 'my_index', 'index1, index2' ]
|
||||
- ref: server.address
|
||||
- ref: server.port
|
||||
- ref: db.elasticsearch.cluster.name
|
||||
requirement_level:
|
||||
recommended: >
|
||||
When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
|
||||
- ref: db.namespace
|
||||
note: >
|
||||
When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.
|
||||
brief: The name of the Elasticsearch cluster which the client connects to.
|
||||
requirement_level: recommended
|
||||
- ref: db.elasticsearch.node.name
|
||||
requirement_level:
|
||||
recommended: >
|
||||
When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
|
||||
note: >
|
||||
When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header.
|
||||
requirement_level: recommended
|
||||
- ref: db.elasticsearch.path_parts
|
||||
requirement_level:
|
||||
conditionally_required: when the url has dynamic values
|
||||
|
|
|
|||
|
|
@ -2,6 +2,12 @@ file_format: 1.1.0
|
|||
schema_url: https://opentelemetry.io/schemas/next
|
||||
versions:
|
||||
next:
|
||||
spans:
|
||||
changes:
|
||||
# https://github.com/open-telemetry/semantic-conventions/pull/1002
|
||||
- rename_attributes:
|
||||
attribute_map:
|
||||
db.elasticsearch.cluster.name: db.namespace
|
||||
metrics:
|
||||
changes:
|
||||
- rename_attributes:
|
||||
|
|
|
|||
Loading…
Reference in New Issue