90 lines
5.8 KiB
Markdown
90 lines
5.8 KiB
Markdown
<!--- Hugo front matter used to generate the website version of this page:
|
|
linkTitle: CouchDB
|
|
--->
|
|
|
|
# Semantic conventions for CouchDB
|
|
|
|
**Status**: [Development][DocumentStatus]
|
|
|
|
<!-- toc -->
|
|
|
|
- [Spans](#spans)
|
|
- [Metrics](#metrics)
|
|
|
|
<!-- tocstop -->
|
|
|
|
The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and override the [Database Semantic Conventions](README.md).
|
|
|
|
## Spans
|
|
|
|
Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md).
|
|
|
|
`db.system.name` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**.
|
|
|
|
The following table outlines the span attributes applicable to CouchDB.
|
|
|
|
<!-- semconv span.db.couchdb.client -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. |  |
|
|
| [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. |  |
|
|
| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB recorded as a string. [2] | `200`; `201`; `429` | `Conditionally Required` [3] |  |
|
|
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `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. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] |  |
|
|
| [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` |  |
|
|
| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the database host. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
|
|
|
**[1] `db.operation.name`:** In **CouchDB**, `db.operation.name` 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.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid).
|
|
|
|
**[2] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors.
|
|
|
|
**[3] `db.response.status_code`:** If response was received and the HTTP response code is available.
|
|
|
|
**[4] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred.
|
|
When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred.
|
|
Instrumentations SHOULD document how `error.type` is populated.
|
|
|
|
**[5] `server.port`:** 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.
|
|
|
|
**[6] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set.
|
|
|
|
**[7] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`.
|
|
|
|
**[8] `server.address`:** 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 following attributes can be important for making sampling decisions
|
|
and SHOULD be provided **at span creation time** (if provided at all):
|
|
|
|
* [`db.namespace`](/docs/attributes-registry/db.md)
|
|
* [`db.operation.name`](/docs/attributes-registry/db.md)
|
|
* [`server.address`](/docs/attributes-registry/server.md)
|
|
* [`server.port`](/docs/attributes-registry/server.md)
|
|
|
|
---
|
|
|
|
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
|
|
|
| Value | Description | Stability |
|
|
|---|---|---|
|
|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
## Metrics
|
|
|
|
CouchDB client instrumentations SHOULD collect metrics according to the general
|
|
[Semantic Conventions for Database Client Metrics](database-metrics.md).
|
|
|
|
`db.system.name` MUST be set to `"couchdb"`.
|
|
|
|
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|