From 3aaa4cd78a8b57200811c4c011f104cb8119da5b Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Thu, 6 Jul 2023 04:33:21 +0000 Subject: [PATCH 01/44] Feat: Add EventToCarrier to AWS Lambda semantic conventions Signed-off-by: Raphael Silva --- specification/faas/aws-lambda.md | 36 ++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/specification/faas/aws-lambda.md b/specification/faas/aws-lambda.md index 34e6a2b0e6..623396e42d 100644 --- a/specification/faas/aws-lambda.md +++ b/specification/faas/aws-lambda.md @@ -14,7 +14,7 @@ use cases. - [All triggers](#all-triggers) - * [AWS X-Ray Environment Span Link](#aws-x-ray-environment-span-link) + * [Determining the remote parent span context](#determining-the-remote-parent-span-context) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) @@ -54,21 +54,31 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faasres]: /specification/resource/semantic_conventions/faas.md (FaaS resource conventions) [cloud]: /specification/resource/semantic_conventions/cloud.md (Cloud resource conventions) -### AWS X-Ray Environment Span Link +### Determining the remote parent span context -If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation SHOULD try to parse an -OpenTelemetry `Context` out of it using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/context/api-propagators.md). If the -resulting `Context` is [valid](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#isvalid) then a [Span Link][] SHOULD be added to the new Span's -[start options](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#specifying-links) with an associated attribute of `source=x-ray-env` to -indicate the source of the linked span. -Instrumentation MUST check if the context is valid before using it because the `_X_AMZN_TRACE_ID` environment variable can -contain an incomplete trace context which indicates X-Ray isn’t enabled. The environment variable will be set and the -`Context` will be valid and sampled only if AWS X-Ray has been enabled for the Lambda function. A user can -disable AWS X-Ray for the function if the X-Ray Span Link is not desired. +Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including TraceID, etc.) as part of the invocation event. If using the AWS XRay tracing then the trace information is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. A single lambda function can be triggered from multiple sources, however spans can only have a single parent. -**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above. +To determine the parent span context, the lambda instrumentation SHOULD use a `EventToCarrier`. `EventToCarrier` defines how the instrumentation should prepare a `Carrier` to be used by subsequent `TextMapPropagators`. -[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links +The `EventToCarrier` MUST implement the `Convert` operation to convert a lammbda `Event` into a `Carrier`. + +The `Convert` operation MUST have the following parameters: + `Carrier` - the carrier that will be populated from the `Event` + `Event` - the lambda event. + +#### Composite EventToCarrier + +Implementations MUST provide a facility to group multiple `EventToCarrier`s. A composite `EventToCarrier` can be built from a list of `EventToCarrier`s. The resulting composite `EventToCarrier` will invoke the `Convert` operation of each individual `EventToCarrier` in the order they were specified, sequentially updating the carrier. + +The list of `EventToCarrier`s passed to the composite `EventToCarrier` MUST be configured using the `OTEL_AWS_LAMBDA_EVENT_TO_CARRIERS`, as a comma separated list of values. + +Valid values to configure the composite `EventToCarrier` are: + +* `lambda_runtime` - populates the `Carrier` with a key `X-Amzn-Trace-Id` from the value of the `_X_AMZN_TRACE_ID` environment variable. (see note below) +* `http_headers` = populates the `Carrier` with the content of the http headers. +* `sqs` - populate the carrier with the content of the `AWSTraceHeader` system attribute of the message. + +**NOTE**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse the `X-Amzn-Trace-Id` out of the system property `com.amazonaws.xray.traceHeader` before checking and attempting to parse the environment variable `_X_AMZN_TRACE_ID`. ## API Gateway From 526dc6518c540b9b57e5f83bbb211d640b2928d2 Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Thu, 6 Jul 2023 04:48:13 +0000 Subject: [PATCH 02/44] Fix: fix TOC Signed-off-by: Raphael Silva --- specification/faas/aws-lambda.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/faas/aws-lambda.md b/specification/faas/aws-lambda.md index 623396e42d..a0a2556645 100644 --- a/specification/faas/aws-lambda.md +++ b/specification/faas/aws-lambda.md @@ -15,6 +15,7 @@ use cases. - [All triggers](#all-triggers) * [Determining the remote parent span context](#determining-the-remote-parent-span-context) + * [Composite EventToCarrier](#composite-eventtocarrier) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) From ab154490cdbe69a4e2c4e085e085da99cbd87797 Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Thu, 6 Jul 2023 04:56:54 +0000 Subject: [PATCH 03/44] Fix: fix toc Signed-off-by: Raphael Silva --- specification/faas/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/faas/aws-lambda.md b/specification/faas/aws-lambda.md index a0a2556645..ec7c20522d 100644 --- a/specification/faas/aws-lambda.md +++ b/specification/faas/aws-lambda.md @@ -15,7 +15,7 @@ use cases. - [All triggers](#all-triggers) * [Determining the remote parent span context](#determining-the-remote-parent-span-context) - * [Composite EventToCarrier](#composite-eventtocarrier) + + [Composite EventToCarrier](#composite-eventtocarrier) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) From 29fdde3afcf13681c12ddf016c3ec979dd3e4bd0 Mon Sep 17 00:00:00 2001 From: Raphael Philipe Mendes da Silva Date: Sun, 13 Aug 2023 22:39:34 -0700 Subject: [PATCH 04/44] Update specification/faas/aws-lambda.md Co-authored-by: Anthony Mirabella --- specification/faas/aws-lambda.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/faas/aws-lambda.md b/specification/faas/aws-lambda.md index ec7c20522d..2b209b6156 100644 --- a/specification/faas/aws-lambda.md +++ b/specification/faas/aws-lambda.md @@ -57,7 +57,7 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a ### Determining the remote parent span context -Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including TraceID, etc.) as part of the invocation event. If using the AWS XRay tracing then the trace information is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. A single lambda function can be triggered from multiple sources, however spans can only have a single parent. +Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including any propagated context, etc.) as part of the invocation event. If using AWS X-Ray tracing then the trace context is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. A single lambda function can be triggered from multiple sources, however spans can only have a single parent. To determine the parent span context, the lambda instrumentation SHOULD use a `EventToCarrier`. `EventToCarrier` defines how the instrumentation should prepare a `Carrier` to be used by subsequent `TextMapPropagators`. From 71f49326730308b859c9d6541af7d41f103cf5ef Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Thu, 6 Jul 2023 19:16:21 +0200 Subject: [PATCH 05/44] Moved resource semconv directly under the resource directory (#165) --- semantic_conventions/resource/os.yaml | 2 +- semantic_conventions/trace/general.yaml | 2 +- specification/README.md | 2 +- specification/exceptions/exceptions-spans.md | 2 +- specification/faas/aws-lambda.md | 4 ++-- specification/faas/faas-metrics.md | 2 +- specification/faas/faas-spans.md | 12 ++++++------ specification/general/general-attributes.md | 2 +- specification/general/logs-general.md | 2 +- specification/general/metrics-general.md | 2 +- specification/general/trace-general.md | 2 +- .../resource/{semantic_conventions => }/README.md | 0 .../resource/{semantic_conventions => }/browser.md | 0 .../resource/{semantic_conventions => }/cloud.md | 0 .../cloud_provider/aws/README.md | 0 .../cloud_provider/aws/ecs.md | 0 .../cloud_provider/aws/eks.md | 0 .../cloud_provider/aws/logs.md | 0 .../cloud_provider/gcp/README.md | 0 .../cloud_provider/gcp/cloud_run.md | 0 .../cloud_provider/gcp/gce.md | 0 .../cloud_provider/heroku.md | 0 .../resource/{semantic_conventions => }/container.md | 0 .../deployment_environment.md | 0 .../resource/{semantic_conventions => }/device.md | 0 .../resource/{semantic_conventions => }/faas.md | 0 .../resource/{semantic_conventions => }/host.md | 0 .../resource/{semantic_conventions => }/k8s.md | 0 .../resource/{semantic_conventions => }/os.md | 2 +- .../resource/{semantic_conventions => }/process.md | 0 .../resource/{semantic_conventions => }/webengine.md | 0 specification/rpc/rpc-metrics.md | 2 +- specification/rpc/rpc-spans.md | 2 +- specification/system/hardware-metrics.md | 2 +- specification/system/process-metrics.md | 2 +- specification/system/runtime-environment-metrics.md | 2 +- 36 files changed, 23 insertions(+), 23 deletions(-) rename specification/resource/{semantic_conventions => }/README.md (100%) rename specification/resource/{semantic_conventions => }/browser.md (100%) rename specification/resource/{semantic_conventions => }/cloud.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/aws/README.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/aws/ecs.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/aws/eks.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/aws/logs.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/gcp/README.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/gcp/cloud_run.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/gcp/gce.md (100%) rename specification/resource/{semantic_conventions => }/cloud_provider/heroku.md (100%) rename specification/resource/{semantic_conventions => }/container.md (100%) rename specification/resource/{semantic_conventions => }/deployment_environment.md (100%) rename specification/resource/{semantic_conventions => }/device.md (100%) rename specification/resource/{semantic_conventions => }/faas.md (100%) rename specification/resource/{semantic_conventions => }/host.md (100%) rename specification/resource/{semantic_conventions => }/k8s.md (100%) rename specification/resource/{semantic_conventions => }/os.md (91%) rename specification/resource/{semantic_conventions => }/process.md (100%) rename specification/resource/{semantic_conventions => }/webengine.md (100%) diff --git a/semantic_conventions/resource/os.yaml b/semantic_conventions/resource/os.yaml index ffccef3281..c1b8c7ef9d 100644 --- a/semantic_conventions/resource/os.yaml +++ b/semantic_conventions/resource/os.yaml @@ -61,5 +61,5 @@ groups: type: string brief: > The version string of the operating system as defined in - [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). + [Version Attributes](/specification/resource/README.md#version-attributes). examples: ['14.2.1', '18.04.1'] diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index b53576a5db..fd1e3136d1 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -170,7 +170,7 @@ groups: - id: service type: string brief: > - The [`service.name`](/specification/resource/semantic_conventions/README.md#service) + The [`service.name`](/specification/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. examples: "AuthTokenCache" diff --git a/specification/README.md b/specification/README.md index 448a6a9153..fe9c908ff0 100644 --- a/specification/README.md +++ b/specification/README.md @@ -24,5 +24,5 @@ Semantic Conventions by signals: * [Events](general/events-general.md): Semantic Conventions for event data. * [Logs](general/logs-general.md): Semantic Conventions for logs data. * [Metrics](general/metrics-general.md): Semantic Conventions for metrics. -* [Resource](resource/semantic_conventions/README.md): Semantic Conventions for resources. +* [Resource](resource/README.md): Semantic Conventions for resources. * [Trace](general/trace-general.md): Semantic Conventions for traces and spans. diff --git a/specification/exceptions/exceptions-spans.md b/specification/exceptions/exceptions-spans.md index 999c975f2b..91476ab9d4 100644 --- a/specification/exceptions/exceptions-spans.md +++ b/specification/exceptions/exceptions-spans.md @@ -102,7 +102,7 @@ grained information from a stacktrace, if necessary. [ruby-full-message]: https://ruby-doc.org/core-2.7.1/Exception.html#method-i-full_message [csharp-stacktrace]: https://docs.microsoft.com/en-us/dotnet/api/system.exception.tostring [go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack -[telemetry-sdk-resource]: ../resource/semantic_conventions/README.md#telemetry-sdk +[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk [erlang-stacktrace]: https://www.erlang.org/doc/man/erl_error.html#format_exception-3 [elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/faas/aws-lambda.md b/specification/faas/aws-lambda.md index 2b209b6156..4a9b93ad59 100644 --- a/specification/faas/aws-lambda.md +++ b/specification/faas/aws-lambda.md @@ -52,8 +52,8 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faas]: faas-spans.md (FaaS trace conventions) -[faasres]: /specification/resource/semantic_conventions/faas.md (FaaS resource conventions) -[cloud]: /specification/resource/semantic_conventions/cloud.md (Cloud resource conventions) +[faasres]: /specification/resource/faas.md (FaaS resource conventions) +[cloud]: /specification/resource/cloud.md (Cloud resource conventions) ### Determining the remote parent span context diff --git a/specification/faas/faas-metrics.md b/specification/faas/faas-metrics.md index 631be8236c..4f63072b1d 100644 --- a/specification/faas/faas-metrics.md +++ b/specification/faas/faas-metrics.md @@ -65,7 +65,7 @@ Below is a table of the attributes to be included on FaaS metric events. | `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](faas-spans.md). -For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../resource/semantic_conventions/faas.md). +For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../resource/faas.md). Outgoing FaaS invocations are identified using the `faas.invoked_*` attributes above. `faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS invocation events only. diff --git a/specification/faas/faas-spans.md b/specification/faas/faas-spans.md index f561665e2b..32f60878e8 100644 --- a/specification/faas/faas-spans.md +++ b/specification/faas/faas-spans.md @@ -32,14 +32,14 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/specification/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. -If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/semantic_conventions/faas.md#function-as-a-service). +If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md#function-as-a-service). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | | `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | -| [`cloud.resource_id`](../resource/semantic_conventions/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| [`cloud.resource_id`](../resource/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | **[1]:** For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -83,7 +83,7 @@ The following well-known definitions MUST be used if you set this attribute and ### Function Name There are 2 locations where the function's name can be recorded: the span name and the -[`faas.name` Resource attribute](../resource/semantic_conventions/faas.md#function-as-a-service). +[`faas.name` Resource attribute](../resource/faas.md#function-as-a-service). It is guaranteed that if `faas.name` attribute is present it will contain the function name, since it is defined in the semantic convention strictly for that @@ -134,7 +134,7 @@ call to invoke the lambda, which is often HTTP). ### Resource attributes as incoming FaaS span attributes -In addition to the attributes listed above, any [FaaS](../resource/semantic_conventions/faas.md) or [cloud](../resource/semantic_conventions/cloud.md) resource attributes MAY +In addition to the attributes listed above, any [FaaS](../resource/faas.md) or [cloud](../resource/cloud.md) resource attributes MAY instead be set as span attributes on incoming FaaS invocation spans: In some FaaS environments some of the information required for resource attributes is only readily available in the context of an invocation (e.g. as part of a "request context" argument) @@ -180,8 +180,8 @@ which the invoked FaaS instance reports about itself, if it's instrumented. | `tencent_cloud` | Tencent Cloud | -[FaaS resource attributes]: ../resource/semantic_conventions/faas.md -[Cloud resource attributes]: ../resource/semantic_conventions/cloud.md +[FaaS resource attributes]: ../resource/faas.md +[Cloud resource attributes]: ../resource/cloud.md ## Function Trigger Type diff --git a/specification/general/general-attributes.md b/specification/general/general-attributes.md index 470f54ffd7..8878f97ea1 100644 --- a/specification/general/general-attributes.md +++ b/specification/general/general-attributes.md @@ -282,7 +282,7 @@ Instrumentations SHOULD provide a way for users to configure this name. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `peer.service` | string | The [`service.name`](/specification/resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | +| `peer.service` | string | The [`service.name`](/specification/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | Examples of `peer.service` that users may specify: diff --git a/specification/general/logs-general.md b/specification/general/logs-general.md index 1df2c582af..507c6ef4f4 100644 --- a/specification/general/logs-general.md +++ b/specification/general/logs-general.md @@ -24,7 +24,7 @@ The following semantic conventions for logs are defined: Apart from semantic conventions for logs, [events](events-general.md), [traces](trace-general.md), and [metrics](metrics-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own -[Resource Semantic Conventions](/specification/resource/semantic_conventions/README.md). +[Resource Semantic Conventions](/specification/resource/README.md). ## General log identification attributes diff --git a/specification/general/metrics-general.md b/specification/general/metrics-general.md index 9fa2cf7b41..3967fec947 100644 --- a/specification/general/metrics-general.md +++ b/specification/general/metrics-general.md @@ -32,7 +32,7 @@ The following semantic conventions surrounding metrics are defined: Apart from semantic conventions for metrics, [traces](trace-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with -their own [Resource Semantic Conventions](/specification/resource/semantic_conventions/README.md). +their own [Resource Semantic Conventions](/specification/resource/README.md). ## General Guidelines diff --git a/specification/general/trace-general.md b/specification/general/trace-general.md index b477e8fd41..a54c737704 100644 --- a/specification/general/trace-general.md +++ b/specification/general/trace-general.md @@ -30,4 +30,4 @@ The following semantic conventions for spans are defined: Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own -[Resource Semantic Conventions](/specification/resource/semantic_conventions/README.md). +[Resource Semantic Conventions](/specification/resource/README.md). diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/README.md similarity index 100% rename from specification/resource/semantic_conventions/README.md rename to specification/resource/README.md diff --git a/specification/resource/semantic_conventions/browser.md b/specification/resource/browser.md similarity index 100% rename from specification/resource/semantic_conventions/browser.md rename to specification/resource/browser.md diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/cloud.md similarity index 100% rename from specification/resource/semantic_conventions/cloud.md rename to specification/resource/cloud.md diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/README.md b/specification/resource/cloud_provider/aws/README.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/aws/README.md rename to specification/resource/cloud_provider/aws/README.md diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md b/specification/resource/cloud_provider/aws/ecs.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/aws/ecs.md rename to specification/resource/cloud_provider/aws/ecs.md diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/eks.md b/specification/resource/cloud_provider/aws/eks.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/aws/eks.md rename to specification/resource/cloud_provider/aws/eks.md diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/logs.md b/specification/resource/cloud_provider/aws/logs.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/aws/logs.md rename to specification/resource/cloud_provider/aws/logs.md diff --git a/specification/resource/semantic_conventions/cloud_provider/gcp/README.md b/specification/resource/cloud_provider/gcp/README.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/gcp/README.md rename to specification/resource/cloud_provider/gcp/README.md diff --git a/specification/resource/semantic_conventions/cloud_provider/gcp/cloud_run.md b/specification/resource/cloud_provider/gcp/cloud_run.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/gcp/cloud_run.md rename to specification/resource/cloud_provider/gcp/cloud_run.md diff --git a/specification/resource/semantic_conventions/cloud_provider/gcp/gce.md b/specification/resource/cloud_provider/gcp/gce.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/gcp/gce.md rename to specification/resource/cloud_provider/gcp/gce.md diff --git a/specification/resource/semantic_conventions/cloud_provider/heroku.md b/specification/resource/cloud_provider/heroku.md similarity index 100% rename from specification/resource/semantic_conventions/cloud_provider/heroku.md rename to specification/resource/cloud_provider/heroku.md diff --git a/specification/resource/semantic_conventions/container.md b/specification/resource/container.md similarity index 100% rename from specification/resource/semantic_conventions/container.md rename to specification/resource/container.md diff --git a/specification/resource/semantic_conventions/deployment_environment.md b/specification/resource/deployment_environment.md similarity index 100% rename from specification/resource/semantic_conventions/deployment_environment.md rename to specification/resource/deployment_environment.md diff --git a/specification/resource/semantic_conventions/device.md b/specification/resource/device.md similarity index 100% rename from specification/resource/semantic_conventions/device.md rename to specification/resource/device.md diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/faas.md similarity index 100% rename from specification/resource/semantic_conventions/faas.md rename to specification/resource/faas.md diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/host.md similarity index 100% rename from specification/resource/semantic_conventions/host.md rename to specification/resource/host.md diff --git a/specification/resource/semantic_conventions/k8s.md b/specification/resource/k8s.md similarity index 100% rename from specification/resource/semantic_conventions/k8s.md rename to specification/resource/k8s.md diff --git a/specification/resource/semantic_conventions/os.md b/specification/resource/os.md similarity index 91% rename from specification/resource/semantic_conventions/os.md rename to specification/resource/os.md index 9344e5ea1c..16798bdfeb 100644 --- a/specification/resource/semantic_conventions/os.md +++ b/specification/resource/os.md @@ -14,7 +14,7 @@ In case of virtualized environments, this is the operating system as it is obser | `os.type` | string | The operating system type. | `windows` | Required | | `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended | | `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | -| `os.version` | string | The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | +| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/specification/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | `os.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. diff --git a/specification/resource/semantic_conventions/process.md b/specification/resource/process.md similarity index 100% rename from specification/resource/semantic_conventions/process.md rename to specification/resource/process.md diff --git a/specification/resource/semantic_conventions/webengine.md b/specification/resource/webengine.md similarity index 100% rename from specification/resource/semantic_conventions/webengine.md rename to specification/resource/webengine.md diff --git a/specification/rpc/rpc-metrics.md b/specification/rpc/rpc-metrics.md index a6eac6d456..3f85cc82f5 100644 --- a/specification/rpc/rpc-metrics.md +++ b/specification/rpc/rpc-metrics.md @@ -138,7 +138,7 @@ For server-side spans `server.port` is optional (it describes the port the clien On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. -[`service.name`]: /specification/resource/semantic_conventions/README.md#service +[`service.name`]: /specification/resource/README.md#service ## Semantic Conventions for specific RPC technologies diff --git a/specification/rpc/rpc-spans.md b/specification/rpc/rpc-spans.md index af32daeb54..b7bb3c0226 100644 --- a/specification/rpc/rpc-spans.md +++ b/specification/rpc/rpc-spans.md @@ -128,7 +128,7 @@ In this example, spans representing client request should have their `peer.servi Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. [network attributes]: /specification/general/general-attributes.md#server-and-client-attributes -[`service.name`]: /specification/resource/semantic_conventions/README.md#service +[`service.name`]: /specification/resource/README.md#service [`peer.service`]: /specification/general/general-attributes.md#general-remote-service-attributes ### Client attributes diff --git a/specification/system/hardware-metrics.md b/specification/system/hardware-metrics.md index 440597af9d..b202f5d695 100644 --- a/specification/system/hardware-metrics.md +++ b/specification/system/hardware-metrics.md @@ -35,7 +35,7 @@ when creating instruments not explicitly defined in the specification. ## Common hardware attributes -All metrics in `hw.` instruments should be attached to a [Host Resource](/specification/resource/semantic_conventions/host.md) +All metrics in `hw.` instruments should be attached to a [Host Resource](/specification/resource/host.md) and therefore inherit its attributes, like `host.id` and `host.name`. Additionally, all metrics in `hw.` instruments have the following attributes: diff --git a/specification/system/process-metrics.md b/specification/system/process-metrics.md index ebf612f1e1..5a5994e43b 100644 --- a/specification/system/process-metrics.md +++ b/specification/system/process-metrics.md @@ -46,6 +46,6 @@ Below is a table of Process metric instruments. ## Attributes -Process metrics SHOULD be associated with a [`process`](/specification/resource/semantic_conventions/process.md#process) resource whose attributes provide additional context about the process. +Process metrics SHOULD be associated with a [`process`](/specification/resource/process.md#process) resource whose attributes provide additional context about the process. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/system/runtime-environment-metrics.md b/specification/system/runtime-environment-metrics.md index d5cbebdc1b..114c5b4b06 100644 --- a/specification/system/runtime-environment-metrics.md +++ b/specification/system/runtime-environment-metrics.md @@ -71,7 +71,7 @@ consider, for example pthreads vs green thread implementations. ## Attributes -[`process.runtime`](/specification/resource/semantic_conventions/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. +[`process.runtime`](/specification/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. ## JVM Metrics From f4a5387955d54d73b10370736f1cb005c3683770 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Thu, 6 Jul 2023 20:43:47 +0200 Subject: [PATCH 06/44] Renamed `specification` and `semantic_conventions` to `model` and `docs` (#166) --- .github/CODEOWNERS | 20 +++++------ CONTRIBUTING.md | 2 +- Makefile | 6 ++-- README.md | 2 +- {specification => docs}/README.md | 0 .../cloud-providers/README.md | 0 .../cloud-providers/aws-sdk.md | 4 +-- {specification => docs}/cloudevents/README.md | 0 .../cloudevents/cloudevents-spans.md | 0 {specification => docs}/database/README.md | 0 {specification => docs}/database/cassandra.md | 0 {specification => docs}/database/cosmosdb.md | 0 {specification => docs}/database/couchdb.md | 0 .../database/database-metrics.md | 6 ++-- .../database/database-spans.md | 0 {specification => docs}/database/dynamodb.md | 2 +- .../database/elasticsearch.md | 0 {specification => docs}/database/graphql.md | 0 {specification => docs}/database/hbase.md | 0 {specification => docs}/database/mongodb.md | 0 {specification => docs}/database/mssql.md | 0 {specification => docs}/database/redis.md | 0 {specification => docs}/database/sql.md | 0 {specification => docs}/exceptions/README.md | 0 .../exceptions/exceptions-logs.md | 0 .../exceptions/exceptions-spans.md | 0 {specification => docs}/faas/README.md | 0 {specification => docs}/faas/aws-lambda.md | 24 ++++++------- {specification => docs}/faas/faas-metrics.md | 4 +-- {specification => docs}/faas/faas-spans.md | 6 ++-- .../feature-flags/README.md | 0 .../feature-flags/feature-flags-logs.md | 0 .../feature-flags/feature-flags-spans.md | 0 {specification => docs}/general/README.md | 0 .../general/events-general.md | 2 +- .../general/general-attributes.md | 2 +- .../general/logs-general.md | 6 ++-- .../general/metrics-general.md | 18 +++++----- .../general/trace-compatibility.md | 0 .../general/trace-general.md | 22 ++++++------ {specification => docs}/http/README.md | 0 {specification => docs}/http/http-metrics.md | 22 ++++++------ {specification => docs}/http/http-spans.md | 6 ++-- {specification => docs}/messaging/README.md | 0 {specification => docs}/messaging/kafka.md | 8 ++--- .../messaging/messaging-spans.md | 4 +-- {specification => docs}/messaging/rabbitmq.md | 0 {specification => docs}/messaging/rocketmq.md | 0 .../object-stores/README.md | 0 {specification => docs}/object-stores/s3.md | 2 +- {specification => docs}/resource/README.md | 0 {specification => docs}/resource/browser.md | 0 {specification => docs}/resource/cloud.md | 0 .../resource/cloud_provider/aws/README.md | 2 +- .../resource/cloud_provider/aws/ecs.md | 0 .../resource/cloud_provider/aws/eks.md | 0 .../resource/cloud_provider/aws/logs.md | 0 .../resource/cloud_provider/gcp/README.md | 0 .../resource/cloud_provider/gcp/cloud_run.md | 0 .../resource/cloud_provider/gcp/gce.md | 0 .../resource/cloud_provider/heroku.md | 0 {specification => docs}/resource/container.md | 0 .../resource/deployment_environment.md | 0 {specification => docs}/resource/device.md | 0 {specification => docs}/resource/faas.md | 8 ++--- {specification => docs}/resource/host.md | 0 {specification => docs}/resource/k8s.md | 0 {specification => docs}/resource/os.md | 2 +- {specification => docs}/resource/process.md | 0 {specification => docs}/resource/webengine.md | 0 {specification => docs}/rpc/README.md | 0 {specification => docs}/rpc/connect-rpc.md | 0 {specification => docs}/rpc/grpc.md | 0 {specification => docs}/rpc/json-rpc.md | 0 {specification => docs}/rpc/rpc-metrics.md | 8 ++--- {specification => docs}/rpc/rpc-spans.md | 8 ++--- {specification => docs}/system/README.md | 0 .../system/hardware-metrics.md | 36 +++++++++---------- .../system/process-metrics.md | 6 ++-- .../system/runtime-environment-metrics.md | 6 ++-- .../system/system-metrics.md | 16 ++++----- .../tools/update_specification_version.sh | 2 +- {semantic_conventions => model}/README.md | 2 +- {semantic_conventions => model}/client.yaml | 0 .../deprecated/http.yaml | 0 .../deprecated/network.yaml | 0 .../destination.yaml | 0 .../exception.yaml | 0 .../http-common.yaml | 6 ++-- .../logs/events.yaml | 0 .../logs/general.yaml | 0 .../logs/log-exception.yaml | 0 .../logs/log-feature_flag.yaml | 0 .../logs/media.yaml | 0 .../metrics/http.yaml | 8 ++--- ...cess-runtime-jvm-metrics-experimental.yaml | 0 .../metrics/process-runtime-jvm-metrics.yaml | 0 .../resource/browser.yaml | 0 .../resource/cloud.yaml | 0 .../resource/cloud_provider/aws/ecs.yaml | 0 .../resource/cloud_provider/aws/eks.yaml | 0 .../resource/cloud_provider/aws/logs.yaml | 0 .../cloud_provider/gcp/cloud_run.yaml | 0 .../resource/cloud_provider/gcp/gce.yaml | 0 .../resource/cloud_provider/heroku.yaml | 0 .../resource/container.yaml | 0 .../resource/deployment_environment.yaml | 0 .../resource/device.yaml | 0 .../resource/faas.yaml | 2 +- .../resource/host.yaml | 0 .../resource/k8s.yaml | 0 .../resource/os.yaml | 2 +- .../resource/process.yaml | 0 .../resource/service.yaml | 0 .../resource/service_experimental.yaml | 0 .../resource/telemetry.yaml | 0 .../resource/telemetry_experimental.yaml | 0 .../resource/webengine.yaml | 0 .../scope/exporter/exporter.yaml | 0 {semantic_conventions => model}/server.yaml | 0 {semantic_conventions => model}/source.yaml | 0 .../trace/aws/lambda.yaml | 0 .../trace/cloudevents.yaml | 0 .../trace/compatibility.yaml | 0 .../trace/database.yaml | 0 .../trace/exporter/exporter.yaml | 0 .../trace/faas.yaml | 0 .../trace/feature-flag.yaml | 0 .../trace/general.yaml | 2 +- .../trace/http.yaml | 4 +-- .../trace/instrumentation/aws-sdk.yml | 0 .../trace/instrumentation/graphql.yml | 0 .../trace/messaging.yaml | 0 .../trace/rpc.yaml | 0 .../trace/trace-exception.yaml | 0 {semantic_conventions => model}/url.yaml | 0 .../user-agent.yaml | 0 .../version.properties | 0 supplementary-guidelines/compatibility/aws.md | 2 +- 139 files changed, 145 insertions(+), 145 deletions(-) rename {specification => docs}/README.md (100%) rename {specification => docs}/cloud-providers/README.md (100%) rename {specification => docs}/cloud-providers/aws-sdk.md (93%) rename {specification => docs}/cloudevents/README.md (100%) rename {specification => docs}/cloudevents/cloudevents-spans.md (100%) rename {specification => docs}/database/README.md (100%) rename {specification => docs}/database/cassandra.md (100%) rename {specification => docs}/database/cosmosdb.md (100%) rename {specification => docs}/database/couchdb.md (100%) rename {specification => docs}/database/database-metrics.md (88%) rename {specification => docs}/database/database-spans.md (100%) rename {specification => docs}/database/dynamodb.md (99%) rename {specification => docs}/database/elasticsearch.md (100%) rename {specification => docs}/database/graphql.md (100%) rename {specification => docs}/database/hbase.md (100%) rename {specification => docs}/database/mongodb.md (100%) rename {specification => docs}/database/mssql.md (100%) rename {specification => docs}/database/redis.md (100%) rename {specification => docs}/database/sql.md (100%) rename {specification => docs}/exceptions/README.md (100%) rename {specification => docs}/exceptions/exceptions-logs.md (100%) rename {specification => docs}/exceptions/exceptions-spans.md (100%) rename {specification => docs}/faas/README.md (100%) rename {specification => docs}/faas/aws-lambda.md (92%) rename {specification => docs}/faas/faas-metrics.md (91%) rename {specification => docs}/faas/faas-spans.md (97%) rename {specification => docs}/feature-flags/README.md (100%) rename {specification => docs}/feature-flags/feature-flags-logs.md (100%) rename {specification => docs}/feature-flags/feature-flags-spans.md (100%) rename {specification => docs}/general/README.md (100%) rename {specification => docs}/general/events-general.md (95%) rename {specification => docs}/general/general-attributes.md (99%) rename {specification => docs}/general/logs-general.md (91%) rename {specification => docs}/general/metrics-general.md (92%) rename {specification => docs}/general/trace-compatibility.md (100%) rename {specification => docs}/general/trace-general.md (55%) rename {specification => docs}/http/README.md (100%) rename {specification => docs}/http/http-metrics.md (96%) rename {specification => docs}/http/http-spans.md (98%) rename {specification => docs}/messaging/README.md (100%) rename {specification => docs}/messaging/kafka.md (95%) rename {specification => docs}/messaging/messaging-spans.md (99%) rename {specification => docs}/messaging/rabbitmq.md (100%) rename {specification => docs}/messaging/rocketmq.md (100%) rename {specification => docs}/object-stores/README.md (100%) rename {specification => docs}/object-stores/s3.md (98%) rename {specification => docs}/resource/README.md (100%) rename {specification => docs}/resource/browser.md (100%) rename {specification => docs}/resource/cloud.md (100%) rename {specification => docs}/resource/cloud_provider/aws/README.md (96%) rename {specification => docs}/resource/cloud_provider/aws/ecs.md (100%) rename {specification => docs}/resource/cloud_provider/aws/eks.md (100%) rename {specification => docs}/resource/cloud_provider/aws/logs.md (100%) rename {specification => docs}/resource/cloud_provider/gcp/README.md (100%) rename {specification => docs}/resource/cloud_provider/gcp/cloud_run.md (100%) rename {specification => docs}/resource/cloud_provider/gcp/gce.md (100%) rename {specification => docs}/resource/cloud_provider/heroku.md (100%) rename {specification => docs}/resource/container.md (100%) rename {specification => docs}/resource/deployment_environment.md (100%) rename {specification => docs}/resource/device.md (100%) rename {specification => docs}/resource/faas.md (93%) rename {specification => docs}/resource/host.md (100%) rename {specification => docs}/resource/k8s.md (100%) rename {specification => docs}/resource/os.md (92%) rename {specification => docs}/resource/process.md (100%) rename {specification => docs}/resource/webengine.md (100%) rename {specification => docs}/rpc/README.md (100%) rename {specification => docs}/rpc/connect-rpc.md (100%) rename {specification => docs}/rpc/grpc.md (100%) rename {specification => docs}/rpc/json-rpc.md (100%) rename {specification => docs}/rpc/rpc-metrics.md (94%) rename {specification => docs}/rpc/rpc-spans.md (97%) rename {specification => docs}/system/README.md (100%) rename {specification => docs}/system/hardware-metrics.md (93%) rename {specification => docs}/system/process-metrics.md (91%) rename {specification => docs}/system/runtime-environment-metrics.md (98%) rename {specification => docs}/system/system-metrics.md (93%) rename {semantic_conventions => model}/README.md (96%) rename {semantic_conventions => model}/client.yaml (100%) rename {semantic_conventions => model}/deprecated/http.yaml (100%) rename {semantic_conventions => model}/deprecated/network.yaml (100%) rename {semantic_conventions => model}/destination.yaml (100%) rename {semantic_conventions => model}/exception.yaml (100%) rename {semantic_conventions => model}/http-common.yaml (93%) rename {semantic_conventions => model}/logs/events.yaml (100%) rename {semantic_conventions => model}/logs/general.yaml (100%) rename {semantic_conventions => model}/logs/log-exception.yaml (100%) rename {semantic_conventions => model}/logs/log-feature_flag.yaml (100%) rename {semantic_conventions => model}/logs/media.yaml (100%) rename {semantic_conventions => model}/metrics/http.yaml (89%) rename {semantic_conventions => model}/metrics/process-runtime-jvm-metrics-experimental.yaml (100%) rename {semantic_conventions => model}/metrics/process-runtime-jvm-metrics.yaml (100%) rename {semantic_conventions => model}/resource/browser.yaml (100%) rename {semantic_conventions => model}/resource/cloud.yaml (100%) rename {semantic_conventions => model}/resource/cloud_provider/aws/ecs.yaml (100%) rename {semantic_conventions => model}/resource/cloud_provider/aws/eks.yaml (100%) rename {semantic_conventions => model}/resource/cloud_provider/aws/logs.yaml (100%) rename {semantic_conventions => model}/resource/cloud_provider/gcp/cloud_run.yaml (100%) rename {semantic_conventions => model}/resource/cloud_provider/gcp/gce.yaml (100%) rename {semantic_conventions => model}/resource/cloud_provider/heroku.yaml (100%) rename {semantic_conventions => model}/resource/container.yaml (100%) rename {semantic_conventions => model}/resource/deployment_environment.yaml (100%) rename {semantic_conventions => model}/resource/device.yaml (100%) rename {semantic_conventions => model}/resource/faas.yaml (96%) rename {semantic_conventions => model}/resource/host.yaml (100%) rename {semantic_conventions => model}/resource/k8s.yaml (100%) rename {semantic_conventions => model}/resource/os.yaml (96%) rename {semantic_conventions => model}/resource/process.yaml (100%) rename {semantic_conventions => model}/resource/service.yaml (100%) rename {semantic_conventions => model}/resource/service_experimental.yaml (100%) rename {semantic_conventions => model}/resource/telemetry.yaml (100%) rename {semantic_conventions => model}/resource/telemetry_experimental.yaml (100%) rename {semantic_conventions => model}/resource/webengine.yaml (100%) rename {semantic_conventions => model}/scope/exporter/exporter.yaml (100%) rename {semantic_conventions => model}/server.yaml (100%) rename {semantic_conventions => model}/source.yaml (100%) rename {semantic_conventions => model}/trace/aws/lambda.yaml (100%) rename {semantic_conventions => model}/trace/cloudevents.yaml (100%) rename {semantic_conventions => model}/trace/compatibility.yaml (100%) rename {semantic_conventions => model}/trace/database.yaml (100%) rename {semantic_conventions => model}/trace/exporter/exporter.yaml (100%) rename {semantic_conventions => model}/trace/faas.yaml (100%) rename {semantic_conventions => model}/trace/feature-flag.yaml (100%) rename {semantic_conventions => model}/trace/general.yaml (99%) rename {semantic_conventions => model}/trace/http.yaml (96%) rename {semantic_conventions => model}/trace/instrumentation/aws-sdk.yml (100%) rename {semantic_conventions => model}/trace/instrumentation/graphql.yml (100%) rename {semantic_conventions => model}/trace/messaging.yaml (100%) rename {semantic_conventions => model}/trace/rpc.yaml (100%) rename {semantic_conventions => model}/trace/trace-exception.yaml (100%) rename {semantic_conventions => model}/url.yaml (100%) rename {semantic_conventions => model}/user-agent.yaml (100%) rename {semantic_conventions => model}/version.properties (100%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5472da421f..4ef9633c60 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -20,19 +20,19 @@ /internal/tools/schema_check.sh @open-telemetry/specs-semconv-approvers @tigrannajaryan # Logs semantic conventions -/semantic_conventions/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/exceptions/exceptions-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/general/events-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan -/specification/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan +/model/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan +/docs/exceptions/exceptions-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/docs/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/docs/general/events-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/docs/general/logs-general.md @open-telemetry/specs-semconv-approvers @tigrannajaryan +/docs/logs/ @open-telemetry/specs-semconv-approvers @tigrannajaryan # JVM semantic conventions approvers -/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers -/semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers +/model/metrics/process-runtime-jvm-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers +/model/metrics/process-runtime-jvm-metrics-experimental.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers # HTTP semantic conventions approvers -/semantic_conventions/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers -/semantic_conventions/trace/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/trace/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers # TODO - Add semconv area experts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a60c91aaa1..c73b5f458a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,7 +53,7 @@ See: ### YAML to Markdown Semantic conventions are declared in YAML files and markdown tables are -generated from these files. Read about semantic convention updates [here](./semantic_conventions/README.md). +generated from these files. Read about semantic convention updates [here](./model/README.md). ### Autoformatting diff --git a/Makefile b/Makefile index 60e67d0803..b02fdc0952 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ MISSPELL_BINARY=bin/misspell MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates -# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! +# Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.18.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. @@ -74,13 +74,13 @@ yamllint: # Generate markdown tables from YAML definitions .PHONY: table-generation table-generation: - docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec \ + docker run --rm -v $(PWD)/model:/source -v $(PWD)/specification:/spec \ otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec # Check if current markdown tables differ from the ones that would be generated from YAML definitions .PHONY: table-check table-check: - docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec \ + docker run --rm -v $(PWD)/model:/source -v $(PWD)/specification:/spec \ otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check .PHONY: schema-check diff --git a/README.md b/README.md index 2843f3076f..ef2030df3e 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This repository is currently using [this specification version][SpecificationVer ## Read the docs -The documentation currently resides in the [specification](specification/README.md) folder. +The documentation currently resides in the [doc](docs/README.md) folder. ## TODOs diff --git a/specification/README.md b/docs/README.md similarity index 100% rename from specification/README.md rename to docs/README.md diff --git a/specification/cloud-providers/README.md b/docs/cloud-providers/README.md similarity index 100% rename from specification/cloud-providers/README.md rename to docs/cloud-providers/README.md diff --git a/specification/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md similarity index 93% rename from specification/cloud-providers/aws-sdk.md rename to docs/cloud-providers/aws-sdk.md index 0812867d3d..08e06ae87b 100644 --- a/specification/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -36,7 +36,7 @@ with the naming guidelines for RPC client spans. The following Semantic Conventions extend the general AWS SDK attributes for specific AWS services: -* [AWS DynamoDB](/specification/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*. -* [AWS S3](/specification/object-stores/s3.md): Semantic Conventions for *AWS S3*. +* [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*. +* [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for *AWS S3*. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/cloudevents/README.md b/docs/cloudevents/README.md similarity index 100% rename from specification/cloudevents/README.md rename to docs/cloudevents/README.md diff --git a/specification/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md similarity index 100% rename from specification/cloudevents/cloudevents-spans.md rename to docs/cloudevents/cloudevents-spans.md diff --git a/specification/database/README.md b/docs/database/README.md similarity index 100% rename from specification/database/README.md rename to docs/database/README.md diff --git a/specification/database/cassandra.md b/docs/database/cassandra.md similarity index 100% rename from specification/database/cassandra.md rename to docs/database/cassandra.md diff --git a/specification/database/cosmosdb.md b/docs/database/cosmosdb.md similarity index 100% rename from specification/database/cosmosdb.md rename to docs/database/cosmosdb.md diff --git a/specification/database/couchdb.md b/docs/database/couchdb.md similarity index 100% rename from specification/database/couchdb.md rename to docs/database/couchdb.md diff --git a/specification/database/database-metrics.md b/docs/database/database-metrics.md similarity index 88% rename from specification/database/database-metrics.md rename to docs/database/database-metrics.md index 42ca828e63..c47b82143b 100644 --- a/specification/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -29,7 +29,7 @@ and units. Below is a table of database client connection pool metric instruments that MUST be used by connection pool instrumentations: -| Name | Instrument | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | |-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| | `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. | @@ -43,7 +43,7 @@ Instrumentation libraries for database client connection pools that collect data following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments MUST NOT be used. -| Name | Instrument ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | |------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| | `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | | `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | @@ -58,6 +58,6 @@ Below is a table of the attributes that MUST be included on all connection pool | Name | Type | Description | Examples | Requirement Level | |-------------|--------|------------------------------------------------------------------------------|----------------|-------------------| -| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/database/database-spans.md b/docs/database/database-spans.md similarity index 100% rename from specification/database/database-spans.md rename to docs/database/database-spans.md diff --git a/specification/database/dynamodb.md b/docs/database/dynamodb.md similarity index 99% rename from specification/database/dynamodb.md rename to docs/database/dynamodb.md index 76ee26a88b..bc3792e66f 100644 --- a/specification/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -3,7 +3,7 @@ **Status**: [Experimental][DocumentStatus] The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) extend and override the general -[AWS SDK Semantic Conventions](/specification/cloud-providers/aws-sdk.md) +[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) that describe common AWS SDK attributes and the [Database Semantic Conventions](database-spans.md). that describe common database operations attributes in addition to the Semantic Conventions described on this page. diff --git a/specification/database/elasticsearch.md b/docs/database/elasticsearch.md similarity index 100% rename from specification/database/elasticsearch.md rename to docs/database/elasticsearch.md diff --git a/specification/database/graphql.md b/docs/database/graphql.md similarity index 100% rename from specification/database/graphql.md rename to docs/database/graphql.md diff --git a/specification/database/hbase.md b/docs/database/hbase.md similarity index 100% rename from specification/database/hbase.md rename to docs/database/hbase.md diff --git a/specification/database/mongodb.md b/docs/database/mongodb.md similarity index 100% rename from specification/database/mongodb.md rename to docs/database/mongodb.md diff --git a/specification/database/mssql.md b/docs/database/mssql.md similarity index 100% rename from specification/database/mssql.md rename to docs/database/mssql.md diff --git a/specification/database/redis.md b/docs/database/redis.md similarity index 100% rename from specification/database/redis.md rename to docs/database/redis.md diff --git a/specification/database/sql.md b/docs/database/sql.md similarity index 100% rename from specification/database/sql.md rename to docs/database/sql.md diff --git a/specification/exceptions/README.md b/docs/exceptions/README.md similarity index 100% rename from specification/exceptions/README.md rename to docs/exceptions/README.md diff --git a/specification/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md similarity index 100% rename from specification/exceptions/exceptions-logs.md rename to docs/exceptions/exceptions-logs.md diff --git a/specification/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md similarity index 100% rename from specification/exceptions/exceptions-spans.md rename to docs/exceptions/exceptions-spans.md diff --git a/specification/faas/README.md b/docs/faas/README.md similarity index 100% rename from specification/faas/README.md rename to docs/faas/README.md diff --git a/specification/faas/aws-lambda.md b/docs/faas/aws-lambda.md similarity index 92% rename from specification/faas/aws-lambda.md rename to docs/faas/aws-lambda.md index 4a9b93ad59..7aac91d1d2 100644 --- a/specification/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -3,13 +3,13 @@ **Status**: [Experimental][DocumentStatus] This document defines how to apply semantic conventions when instrumenting an AWS Lambda request handler. AWS -Lambda largely follows the conventions for [FaaS][faas] while [HTTP](/specification/http/http-spans.md) conventions are also +Lambda largely follows the conventions for [FaaS][faas] while [HTTP](/docs/http/http-spans.md) conventions are also applicable when handlers are for HTTP requests. There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the use cases. - + @@ -52,8 +52,8 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a [faas]: faas-spans.md (FaaS trace conventions) -[faasres]: /specification/resource/faas.md (FaaS resource conventions) -[cloud]: /specification/resource/cloud.md (Cloud resource conventions) +[faasres]: /docs/resource/faas.md (FaaS resource conventions) +[cloud]: /docs/resource/cloud.md (Cloud resource conventions) ### Determining the remote parent span context @@ -89,11 +89,11 @@ configuration for a REST API, in which case only a deserialized body payload is gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all the information about the HTTP request in the form of an API Gateway Proxy Request Event. -The Lambda span name and the [`http.route` span attribute](/specification/http/http-spans.md#http-server-semantic-conventions) SHOULD +The Lambda span name and the [`http.route` span attribute](/docs/http/http-spans.md#http-server-semantic-conventions) SHOULD be set to the [resource property][] from the proxy request event, which corresponds to the user configured HTTP route instead of the function name. -[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](/specification/http/http-spans.md) SHOULD be set based on the +[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](/docs/http/http-spans.md) SHOULD be set based on the available information in the Lambda event initiated by the proxy request. `http.scheme` is available as the `x-forwarded-proto` header in the Lambda event. Refer to the [input event format][] for more details. @@ -125,9 +125,9 @@ added as a link to the span. This means the span may have as many links as messa See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. -- [`messaging.operation`](/specification/messaging/messaging-spans.md) MUST be set to `process`. -- [`messaging.system`](/specification/messaging/messaging-spans.md) MUST be set to `AmazonSQS`. -- [`messaging.destination.kind` or `messaging.source.kind`](/specification/messaging/messaging-spans.md#messaging-attributes) MUST be set to `queue`. +- [`messaging.operation`](/docs/messaging/messaging-spans.md) MUST be set to `process`. +- [`messaging.system`](/docs/messaging/messaging-spans.md) MUST be set to `AmazonSQS`. +- [`messaging.destination.kind` or `messaging.source.kind`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `queue`. ### SQS Message @@ -139,10 +139,10 @@ added as a link to the span. See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`faas.trigger`][faas] MUST be set to `pubsub`. -- [`messaging.operation`](/specification/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`. -- [`messaging.system`](/specification/messaging/messaging-spans.md#messaging-attributes) MUST be set to `AmazonSQS`. +- [`messaging.operation`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`. +- [`messaging.system`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `AmazonSQS`. -Other [Messaging attributes](/specification/messaging/messaging-spans.md#messaging-attributes) SHOULD be set based on the available information in the SQS message +Other [Messaging attributes](/docs/messaging/messaging-spans.md#messaging-attributes) SHOULD be set based on the available information in the SQS message event. Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` in instrumentation for SQS diff --git a/specification/faas/faas-metrics.md b/docs/faas/faas-metrics.md similarity index 91% rename from specification/faas/faas-metrics.md rename to docs/faas/faas-metrics.md index 4f63072b1d..a2958e9e66 100644 --- a/specification/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -36,7 +36,7 @@ type and units. Below is a table of FaaS invocation metric instruments. -| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | |------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| | `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | | `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | @@ -47,7 +47,7 @@ Below is a table of FaaS invocation metric instruments. Optionally, when applicable: -| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | |------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------| | `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | | `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of CPU usage per invocation | diff --git a/specification/faas/faas-spans.md b/docs/faas/faas-spans.md similarity index 97% rename from specification/faas/faas-spans.md rename to docs/faas/faas-spans.md index 32f60878e8..28847e3da7 100644 --- a/specification/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -30,7 +30,7 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m ## General Attributes -Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/specification/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. +Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md#function-as-a-service). @@ -211,14 +211,14 @@ FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOUL ### HTTP -The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](/specification/http/http-spans.md#http-server-semantic-conventions). +The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). ### PubSub A function is set to be executed when messages are sent to a messaging system. In this case, multiple messages could be batch and forwarded at once to the same function invocation. Therefore, a different root span of type `faas` MUST be created for each message processed by the function, -following the [Messaging systems semantic conventions](/specification/messaging/messaging-spans.md). +following the [Messaging systems semantic conventions](/docs/messaging/messaging-spans.md). This way, it is possible to correlate each individual message with its invocation sender. ### Timer diff --git a/specification/feature-flags/README.md b/docs/feature-flags/README.md similarity index 100% rename from specification/feature-flags/README.md rename to docs/feature-flags/README.md diff --git a/specification/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md similarity index 100% rename from specification/feature-flags/feature-flags-logs.md rename to docs/feature-flags/feature-flags-logs.md diff --git a/specification/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md similarity index 100% rename from specification/feature-flags/feature-flags-spans.md rename to docs/feature-flags/feature-flags-spans.md diff --git a/specification/general/README.md b/docs/general/README.md similarity index 100% rename from specification/general/README.md rename to docs/general/README.md diff --git a/specification/general/events-general.md b/docs/general/events-general.md similarity index 95% rename from specification/general/events-general.md rename to docs/general/events-general.md index 4b9636ce37..a245cbdfa0 100644 --- a/specification/general/events-general.md +++ b/docs/general/events-general.md @@ -8,7 +8,7 @@ in the data model by `LogRecord`s. The following semantic conventions for events are defined: * **[General](#general-event-attributes): General semantic attributes that may be used in describing Events.** -* [Exceptions](/specification/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions as events. +* [Exceptions](/docs/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions as events. ## General event attributes diff --git a/specification/general/general-attributes.md b/docs/general/general-attributes.md similarity index 99% rename from specification/general/general-attributes.md rename to docs/general/general-attributes.md index 8878f97ea1..427cffed4b 100644 --- a/specification/general/general-attributes.md +++ b/docs/general/general-attributes.md @@ -282,7 +282,7 @@ Instrumentations SHOULD provide a way for users to configure this name. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `peer.service` | string | The [`service.name`](/specification/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | +| `peer.service` | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | Examples of `peer.service` that users may specify: diff --git a/specification/general/logs-general.md b/docs/general/logs-general.md similarity index 91% rename from specification/general/logs-general.md rename to docs/general/logs-general.md index 507c6ef4f4..1cd603ca9a 100644 --- a/specification/general/logs-general.md +++ b/docs/general/logs-general.md @@ -19,12 +19,12 @@ They may be used in any Log Record they apply to. The following semantic conventions for logs are defined: * **[General](#general-log-identification-attributes): General semantic attributes that may be used in describing Log Records.** -* [Exceptions](/specification/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions in logs. -* [Feature Flags](/specification/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. +* [Exceptions](/docs/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions in logs. +* [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. Apart from semantic conventions for logs, [events](events-general.md), [traces](trace-general.md), and [metrics](metrics-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own -[Resource Semantic Conventions](/specification/resource/README.md). +[Resource Semantic Conventions](/docs/resource/README.md). ## General log identification attributes diff --git a/specification/general/metrics-general.md b/docs/general/metrics-general.md similarity index 92% rename from specification/general/metrics-general.md rename to docs/general/metrics-general.md index 3967fec947..23135a8151 100644 --- a/specification/general/metrics-general.md +++ b/docs/general/metrics-general.md @@ -20,19 +20,19 @@ The following semantic conventions surrounding metrics are defined: * **[General Guidelines](#general-guidelines): General metrics guidelines.** -* [Database](/specification/database/database-metrics.md): For SQL and NoSQL client metrics. -* [FaaS](/specification/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. -* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics. -* [RPC](/specification/rpc/rpc-metrics.md): For RPC client and server metrics. +* [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics. +* [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. +* [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics. +* [RPC](/docs/rpc/rpc-metrics.md): For RPC client and server metrics. * **System metrics** - * [System](/specification/system/system-metrics.md): For standard system metrics. - * [Hardware](/specification/system/hardware-metrics.md): For hardware-related metrics. - * [Process](/specification/system/process-metrics.md): For standard process metrics. - * [Runtime Environment](/specification/system/runtime-environment-metrics.md): For runtime environment metrics. + * [System](/docs/system/system-metrics.md): For standard system metrics. + * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. + * [Process](/docs/system/process-metrics.md): For standard process metrics. + * [Runtime Environment](/docs/system/runtime-environment-metrics.md): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with -their own [Resource Semantic Conventions](/specification/resource/README.md). +their own [Resource Semantic Conventions](/docs/resource/README.md). ## General Guidelines diff --git a/specification/general/trace-compatibility.md b/docs/general/trace-compatibility.md similarity index 100% rename from specification/general/trace-compatibility.md rename to docs/general/trace-compatibility.md diff --git a/specification/general/trace-general.md b/docs/general/trace-general.md similarity index 55% rename from specification/general/trace-general.md rename to docs/general/trace-general.md index a54c737704..71d1b110d5 100644 --- a/specification/general/trace-general.md +++ b/docs/general/trace-general.md @@ -17,17 +17,17 @@ The following semantic conventions for spans are defined: * **[General](general-attributes.md): General semantic attributes that may be used in describing different kinds of operations.** * [Compatibility](trace-compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer. -* [CloudEvents](/specification/cloudevents/README.md): Semantic Conventions for the CloudEvents spans. -* [Cloud Providers](/specification/cloud-providers/README.md): Semantic Conventions for cloud providers spans. -* [Database](/specification/database/database-spans.md): For SQL and NoSQL client call spans. -* [Exceptions](/specification/exceptions/exceptions-spans.md): For recording exceptions associated with a span. -* [FaaS](/specification/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. -* [Feature Flags](/specification/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. -* [HTTP](/specification/http/http-spans.md): For HTTP client and server spans. -* [Messaging](/specification/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. -* [Object Stores](/specification/object-stores/README.md): Semantic Conventions for object stores spans. -* [RPC/RMI](/specification/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. +* [CloudEvents](/docs/cloudevents/README.md): Semantic Conventions for the CloudEvents spans. +* [Cloud Providers](/docs/cloud-providers/README.md): Semantic Conventions for cloud providers spans. +* [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. +* [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. +* [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. +* [Feature Flags](/docs/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. +* [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. +* [Messaging](/docs/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. +* [Object Stores](/docs/object-stores/README.md): Semantic Conventions for object stores spans. +* [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own -[Resource Semantic Conventions](/specification/resource/README.md). +[Resource Semantic Conventions](/docs/resource/README.md). diff --git a/specification/http/README.md b/docs/http/README.md similarity index 100% rename from specification/http/README.md rename to docs/http/README.md diff --git a/specification/http/http-metrics.md b/docs/http/http-metrics.md similarity index 96% rename from specification/http/http-metrics.md rename to docs/http/http-metrics.md index 402f35a6de..43b37ace2b 100644 --- a/specification/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -84,7 +84,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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](/specification/http/http-spans.md#http-server-definitions) if there is one. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. **[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) @@ -106,7 +106,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4]:** Determined by using the first of the following that applies -- The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -116,7 +116,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header @@ -175,7 +175,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[2]:** Determined by using the first of the following that applies -- The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -185,7 +185,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[3]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header @@ -231,7 +231,7 @@ This metric is optional. | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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](/specification/http/http-spans.md#http-server-definitions) if there is one. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. **[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) @@ -253,7 +253,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4]:** Determined by using the first of the following that applies -- The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -263,7 +263,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header @@ -309,7 +309,7 @@ This metric is optional. | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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](/specification/http/http-spans.md#http-server-definitions) if there is one. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. **[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) @@ -331,7 +331,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4]:** Determined by using the first of the following that applies -- The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -341,7 +341,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header diff --git a/specification/http/http-spans.md b/docs/http/http-spans.md similarity index 98% rename from specification/http/http-spans.md rename to docs/http/http-spans.md index cc80ba2376..553fdbf938 100644 --- a/specification/http/http-spans.md +++ b/docs/http/http-spans.md @@ -336,7 +336,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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](/specification/http/http-spans.md#http-server-definitions) if there is one. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. **[2]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. @@ -344,7 +344,7 @@ SHOULD include the [application root](/specification/http/http-spans.md#http-ser **[4]:** Determined by using the first of the following that applies -- The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -354,7 +354,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header diff --git a/specification/messaging/README.md b/docs/messaging/README.md similarity index 100% rename from specification/messaging/README.md rename to docs/messaging/README.md diff --git a/specification/messaging/kafka.md b/docs/messaging/kafka.md similarity index 95% rename from specification/messaging/kafka.md rename to docs/messaging/kafka.md index d51677b02c..979189fc91 100644 --- a/specification/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -42,7 +42,7 @@ For Apache Kafka, the following additional attributes are defined: **[2]:** If value is `true`. When missing, the value is assumed to be `false`. -For Apache Kafka producers, [`peer.service`](/specification/general/general-attributes.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to. +For Apache Kafka producers, [`peer.service`](/docs/general/general-attributes.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to. The `service.name` of a Consumer's Resource SHOULD match the `peer.service` of the Producer, when the message is directly passed to another service. If an intermediary broker is present, `service.name` and `peer.service` will not be the same. @@ -96,7 +96,7 @@ This section defines how to apply semantic conventions when collecting Kafka met **Description:** General Kafka metrics. -| Name | Instrument | Value type | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | +| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | | ---------------------------------------------| ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | | messaging.kafka.messages | Counter | Int64 | messages | `{message}` | The number of messages received by the broker. | | | | messaging.kafka.requests.failed | Counter | Int64 | requests | `{request}` | The number of requests to the broker resulting in a failure. | `type` | `produce`, `fetch` | @@ -126,7 +126,7 @@ This section defines how to apply semantic conventions when collecting Kafka met **Description:** Kafka Producer level metrics. -| Name | Instrument | Value type | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | +| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | | --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | | messaging.kafka.producer.outgoing-bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of outgoing bytes sent per second to all servers. | `client-id` | `client-id` value | | messaging.kafka.producer.responses.rate | Gauge | Double | responses per second | `{response}/s` | The average number of responses received per second. | `client-id` | `client-id` value | @@ -145,7 +145,7 @@ This section defines how to apply semantic conventions when collecting Kafka met **Description:** Kafka Consumer level metrics. -| Name | Instrument | Value type | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | +| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | | --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | | messaging.kafka.consumer.members | UpDownCounter | Int64 | members | `{member}` | Count of members in the consumer group | `group` | The ID (string) of a consumer group | | messaging.kafka.consumer.offset | Gauge | Int64 | offset | `{offset}` | Current offset of the consumer group at partition of topic | `group` | The ID (string) of a consumer group | diff --git a/specification/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md similarity index 99% rename from specification/messaging/messaging-spans.md rename to docs/messaging/messaging-spans.md index dbabf55627..14f63ffada 100644 --- a/specification/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -292,8 +292,8 @@ Communication with broker is described with general [network attributes]. Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). -[network attributes]: /specification/general/general-attributes.md#server-and-client-attributes -[`network.transport`]: /specification/general/general-attributes.md#network-attributes +[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes +[`network.transport`]: /docs/general/general-attributes.md#network-attributes [Hangfire]: https://www.hangfire.io/ ### Consumer attributes diff --git a/specification/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md similarity index 100% rename from specification/messaging/rabbitmq.md rename to docs/messaging/rabbitmq.md diff --git a/specification/messaging/rocketmq.md b/docs/messaging/rocketmq.md similarity index 100% rename from specification/messaging/rocketmq.md rename to docs/messaging/rocketmq.md diff --git a/specification/object-stores/README.md b/docs/object-stores/README.md similarity index 100% rename from specification/object-stores/README.md rename to docs/object-stores/README.md diff --git a/specification/object-stores/s3.md b/docs/object-stores/s3.md similarity index 98% rename from specification/object-stores/s3.md rename to docs/object-stores/s3.md index 123685003c..501f07f4ba 100644 --- a/specification/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -3,7 +3,7 @@ **Status**: [Experimental][DocumentStatus] The Semantic Conventions for AWS S3 extend the general -[AWS SDK Semantic Conventions](/specification/cloud-providers/aws-sdk.md) +[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) that describe common AWS SDK attributes in addition to the Semantic Conventions described on this page. diff --git a/specification/resource/README.md b/docs/resource/README.md similarity index 100% rename from specification/resource/README.md rename to docs/resource/README.md diff --git a/specification/resource/browser.md b/docs/resource/browser.md similarity index 100% rename from specification/resource/browser.md rename to docs/resource/browser.md diff --git a/specification/resource/cloud.md b/docs/resource/cloud.md similarity index 100% rename from specification/resource/cloud.md rename to docs/resource/cloud.md diff --git a/specification/resource/cloud_provider/aws/README.md b/docs/resource/cloud_provider/aws/README.md similarity index 96% rename from specification/resource/cloud_provider/aws/README.md rename to docs/resource/cloud_provider/aws/README.md index 6c0040359b..56032980ef 100644 --- a/specification/resource/cloud_provider/aws/README.md +++ b/docs/resource/cloud_provider/aws/README.md @@ -5,7 +5,7 @@ This directory defines standards for resource attributes that only apply to Amazon Web Services (AWS) resources. If an attribute could apply to resources from more than one cloud provider (like account ID, operating system, etc), it belongs in the parent -`semantic_conventions` directory. +`model` directory. ## Generic AWS Attributes diff --git a/specification/resource/cloud_provider/aws/ecs.md b/docs/resource/cloud_provider/aws/ecs.md similarity index 100% rename from specification/resource/cloud_provider/aws/ecs.md rename to docs/resource/cloud_provider/aws/ecs.md diff --git a/specification/resource/cloud_provider/aws/eks.md b/docs/resource/cloud_provider/aws/eks.md similarity index 100% rename from specification/resource/cloud_provider/aws/eks.md rename to docs/resource/cloud_provider/aws/eks.md diff --git a/specification/resource/cloud_provider/aws/logs.md b/docs/resource/cloud_provider/aws/logs.md similarity index 100% rename from specification/resource/cloud_provider/aws/logs.md rename to docs/resource/cloud_provider/aws/logs.md diff --git a/specification/resource/cloud_provider/gcp/README.md b/docs/resource/cloud_provider/gcp/README.md similarity index 100% rename from specification/resource/cloud_provider/gcp/README.md rename to docs/resource/cloud_provider/gcp/README.md diff --git a/specification/resource/cloud_provider/gcp/cloud_run.md b/docs/resource/cloud_provider/gcp/cloud_run.md similarity index 100% rename from specification/resource/cloud_provider/gcp/cloud_run.md rename to docs/resource/cloud_provider/gcp/cloud_run.md diff --git a/specification/resource/cloud_provider/gcp/gce.md b/docs/resource/cloud_provider/gcp/gce.md similarity index 100% rename from specification/resource/cloud_provider/gcp/gce.md rename to docs/resource/cloud_provider/gcp/gce.md diff --git a/specification/resource/cloud_provider/heroku.md b/docs/resource/cloud_provider/heroku.md similarity index 100% rename from specification/resource/cloud_provider/heroku.md rename to docs/resource/cloud_provider/heroku.md diff --git a/specification/resource/container.md b/docs/resource/container.md similarity index 100% rename from specification/resource/container.md rename to docs/resource/container.md diff --git a/specification/resource/deployment_environment.md b/docs/resource/deployment_environment.md similarity index 100% rename from specification/resource/deployment_environment.md rename to docs/resource/deployment_environment.md diff --git a/specification/resource/device.md b/docs/resource/device.md similarity index 100% rename from specification/resource/device.md rename to docs/resource/device.md diff --git a/specification/resource/faas.md b/docs/resource/faas.md similarity index 93% rename from specification/resource/faas.md rename to docs/resource/faas.md index dd6ceab955..b050716c6c 100644 --- a/specification/resource/faas.md +++ b/docs/resource/faas.md @@ -8,7 +8,7 @@ See also: -- The [Trace semantic conventions for FaaS](/specification/faas/faas-spans.md) +- The [Trace semantic conventions for FaaS](/docs/faas/faas-spans.md) - The [Cloud resource conventions](cloud.md) ## FaaS resource attributes @@ -25,7 +25,7 @@ See also: **[1]:** This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback function (which may be stored in the -[`code.namespace`/`code.function`](/specification/general/general-attributes.md#source-code-attributes) +[`code.namespace`/`code.function`](/docs/general/general-attributes.md#source-code-attributes) span attributes). For some cloud providers, the above definition is ambiguous. The following @@ -72,12 +72,12 @@ The following well-known definitions MUST be used if you set this attribute and a TracerProvider. -Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](/specification/faas/faas-spans.md#difference-between-invocation-and-instance). +Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](/docs/faas/faas-spans.md#difference-between-invocation-and-instance). ## Using span attributes instead of resource attributes There are cases where a FaaS resource attribute is better applied as a span attribute instead. -See the [FaaS trace conventions](/specification/faas/faas-spans.md) for more. +See the [FaaS trace conventions](/docs/faas/faas-spans.md) for more. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/resource/host.md b/docs/resource/host.md similarity index 100% rename from specification/resource/host.md rename to docs/resource/host.md diff --git a/specification/resource/k8s.md b/docs/resource/k8s.md similarity index 100% rename from specification/resource/k8s.md rename to docs/resource/k8s.md diff --git a/specification/resource/os.md b/docs/resource/os.md similarity index 92% rename from specification/resource/os.md rename to docs/resource/os.md index 16798bdfeb..05780ace78 100644 --- a/specification/resource/os.md +++ b/docs/resource/os.md @@ -14,7 +14,7 @@ In case of virtualized environments, this is the operating system as it is obser | `os.type` | string | The operating system type. | `windows` | Required | | `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended | | `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | -| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/specification/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | +| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | `os.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. diff --git a/specification/resource/process.md b/docs/resource/process.md similarity index 100% rename from specification/resource/process.md rename to docs/resource/process.md diff --git a/specification/resource/webengine.md b/docs/resource/webengine.md similarity index 100% rename from specification/resource/webengine.md rename to docs/resource/webengine.md diff --git a/specification/rpc/README.md b/docs/rpc/README.md similarity index 100% rename from specification/rpc/README.md rename to docs/rpc/README.md diff --git a/specification/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md similarity index 100% rename from specification/rpc/connect-rpc.md rename to docs/rpc/connect-rpc.md diff --git a/specification/rpc/grpc.md b/docs/rpc/grpc.md similarity index 100% rename from specification/rpc/grpc.md rename to docs/rpc/grpc.md diff --git a/specification/rpc/json-rpc.md b/docs/rpc/json-rpc.md similarity index 100% rename from specification/rpc/json-rpc.md rename to docs/rpc/json-rpc.md diff --git a/specification/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md similarity index 94% rename from specification/rpc/rpc-metrics.md rename to docs/rpc/rpc-metrics.md index 3f85cc82f5..7afbe316d3 100644 --- a/specification/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,7 +61,7 @@ MUST be of the specified type and units. Below is a table of RPC server metric instruments. -| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Status | Streaming | +| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Status | Streaming | |------|------------|------|-------------------------------------------|-------------|--------|-----------| | `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | | `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | @@ -74,7 +74,7 @@ Below is a table of RPC server metric instruments. Below is a table of RPC client metric instruments. These apply to traditional RPC usage, not streaming RPCs. -| Name | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/specification/general/metrics-general.md#instrument-units)) | Description | Status | Streaming | +| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Status | Streaming | |------|------------|------|-------------------------------------------|-------------|--------|-----------| | `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | | `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | @@ -131,14 +131,14 @@ To avoid high cardinality, implementations should prefer the most stable of `ser For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For server-side spans `server.port` is optional (it describes the port the client is connecting from). -[network.transport]: /specification/general/general-attributes.md#network-attributes +[network.transport]: /docs/general/general-attributes.md#network-attributes ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. -[`service.name`]: /specification/resource/README.md#service +[`service.name`]: /docs/resource/README.md#service ## Semantic Conventions for specific RPC technologies diff --git a/specification/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md similarity index 97% rename from specification/rpc/rpc-spans.md rename to docs/rpc/rpc-spans.md index b7bb3c0226..66f7c62daa 100644 --- a/specification/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -127,9 +127,9 @@ This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. -[network attributes]: /specification/general/general-attributes.md#server-and-client-attributes -[`service.name`]: /specification/resource/README.md#service -[`peer.service`]: /specification/general/general-attributes.md#general-remote-service-attributes +[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes +[`service.name`]: /docs/resource/README.md#service +[`peer.service`]: /docs/general/general-attributes.md#general-remote-service-attributes ### Client attributes @@ -188,7 +188,7 @@ The event name MUST be `message`. ### Distinction from HTTP spans -HTTP calls can generally be represented using just [HTTP spans](/specification/http/http-spans.md). +HTTP calls can generally be represented using just [HTTP spans](/docs/http/http-spans.md). If they address a particular remote service and method known to the caller, i.e., when it is a remote procedure call transported over HTTP, the `rpc.*` attributes might be added additionally on that span, or in a separate RPC span that is a parent of the transporting HTTP call. Note that *method* in this context is about the called remote procedure and *not* the HTTP verb (GET, POST, etc.). diff --git a/specification/system/README.md b/docs/system/README.md similarity index 100% rename from specification/system/README.md rename to docs/system/README.md diff --git a/specification/system/hardware-metrics.md b/docs/system/hardware-metrics.md similarity index 93% rename from specification/system/hardware-metrics.md rename to docs/system/hardware-metrics.md index b202f5d695..596fc56b6b 100644 --- a/specification/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -7,7 +7,7 @@ linkTitle: Hardware **Status**: [Experimental][DocumentStatus] This document describes instruments and attributes for common hardware level -metrics in OpenTelemetry. Consider the [general metric semantic conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions) +metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. @@ -35,7 +35,7 @@ when creating instruments not explicitly defined in the specification. ## Common hardware attributes -All metrics in `hw.` instruments should be attached to a [Host Resource](/specification/resource/host.md) +All metrics in `hw.` instruments should be attached to a [Host Resource](/docs/resource/host.md) and therefore inherit its attributes, like `host.id` and `host.name`. Additionally, all metrics in `hw.` instruments have the following attributes: @@ -52,7 +52,7 @@ Additionally, all metrics in `hw.` instruments have the following attributes: The below metrics apply to any type of hardware component. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ----------- | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | -------------------------- | | `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | | | `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `hw.error.type` (Recommended) | | @@ -75,7 +75,7 @@ monitored component: **Description:** Physical system as opposed to a virtual system or a container. Examples: physical server, switch or disk array. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ---------------- | | `hw.host.ambient_temperature` | Ambient (external) temperature of the physical host | Cel | Gauge | Double | | | | `hw.host.energy` | Total energy consumed by the entire physical host, in joules | J | Counter | Int64 | | | @@ -92,7 +92,7 @@ Examples: physical server, switch or disk array. **Description:** A battery in a computer system or an UPS. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------- | ----------------------------------------------------- | | `hw.battery.charge` | Remaining fraction of battery charge | 1 | Gauge | Double | | | | `hw.battery.charge.limit` | Lower limit of battery charge fraction to ensure proper operation | 1 | Gauge | Double | `limit_type` (Recommended) | `critical`, `throttled`, `degraded` | @@ -116,7 +116,7 @@ describe the characteristics of the monitored battery: the operating system for multi-core systems). A physical processor may include many individual cores. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- | | `hw.errors` | Total number of errors encountered and corrected by the CPU | {error} | Counter | Int64 | `hw.type` (**Required**) | `cpu` | | `hw.cpu.speed` | CPU current frequency | Hz | Gauge | Int64 | | | @@ -136,7 +136,7 @@ Additional **Recommended** attributes: **Description:** Controller that controls the physical disks and organize them in RAID sets and logical disks that are exposed to the operating system. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | | `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | | | | | | | `hw.type` (**Required**) | `disk_controller` | @@ -156,7 +156,7 @@ Additional **Recommended** attributes: **Description:** Computer chassis (can be an expansion enclosure) -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | ---------------------------------- | | `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `open` | | | | | | | `hw.type` (**Required**) | `enclosure` | @@ -176,7 +176,7 @@ Additional **Recommended** attributes: **Description:** Fan that keeps the air flowing to maintain the internal temperature of a computer -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------------ | ------------------------------------- | | `hw.fan.speed` | Fan speed in revolutions per minute | rpm | Gauge | Int | | | | `hw.fan.speed.limit` | Speed limit in rpm | rpm | Gauge | Int | `limit_type` (**Recommended**) | `low.critical`, `low.degraded`, `max` | @@ -194,7 +194,7 @@ Additional **Recommended** attributes: **Description:** Graphics Processing Unit (discrete) -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | ----------------------------------------------- | | `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `corrected`, `uncorrected` | | | | | | | `hw.type` (**Required**) | `gpu` | @@ -223,7 +223,7 @@ Additional **Recommended** attributes: controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed as /dev/hdd0 by the controller). -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | | `hw.errors` | Number of errors encountered on this logical disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `logical_disk` | | `hw.logical_disk.limit` | Size of the logical disk | By | UpDownCounter | Int64 | | | @@ -242,7 +242,7 @@ Additional **Recommended** attributes: **Description:** A memory module in a computer system. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------- | | `hw.errors` | Number of errors encountered on this memory module | {error} | Counter | Int64 | `hw.type` (**Required**) | `memory` | | `hw.memory.size` | Size of the memory module | By | UpDownCounter | Int64 | | | @@ -265,7 +265,7 @@ Additional **Recommended** attributes: physical network interface on a server, switch, router or firewall, an HBA, a fiber channel port or a Wi-Fi adapter. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | ----------------------------- | --------------------------------- | | `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. | | | | | | | `hw.type` (**Required**) | `network` | @@ -292,7 +292,7 @@ Additional **Recommended** attributes: **Description:** Physical hard drive (HDD or SDD) -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- | | `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `bad_sector`, `write`, etc. | | | | | | | `hw.type` (**Required**) | `physical_disk` | @@ -317,7 +317,7 @@ Additional **Recommended** attributes: **Description:** Power supply converting AC current to DC used by the motherboard and the GPUs -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ------------------------------ | | `hw.power_supply.limit` | Maximum power output of the power supply | W | UpDownCounter | Int64 | `limit_type` (Recommended) | `max`, `critical`, `throttled` | | `hw.power_supply.utilization` | Utilization of the power supply as a fraction of its maximum output | 1 | Gauge | Double | | | @@ -337,7 +337,7 @@ Additional **Recommended** attributes: **Description:** A tape drive in a computer or in a tape library (excluding virtual tape libraries) -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- | | `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.error.type` | `read`, `write`, `mount`, etc. | | | | | | | `hw.type` (**Required**) | `tape_drive` | @@ -357,7 +357,7 @@ Additional **Recommended** attributes: **Description:** A temperature sensor, either numeric or discrete -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------------- | --------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | | `hw.temperature` | Temperature in degrees Celsius | Cel | Gauge | Double | | | | `hw.temperature.limit` | Temperature limit in degrees Celsius | Cel | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | @@ -374,7 +374,7 @@ Additional **Recommended** attributes: **Description:** A voltage sensor, either numeric or discrete -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------- | ----------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | | `hw.voltage.limit` | Voltage limit in Volts | V | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | | `hw.voltage.nominal` | Nominal (expected) voltage | V | Gauge | Double | | | diff --git a/specification/system/process-metrics.md b/docs/system/process-metrics.md similarity index 91% rename from specification/system/process-metrics.md rename to docs/system/process-metrics.md index 5a5994e43b..93e1c5bf60 100644 --- a/specification/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -8,7 +8,7 @@ linkTitle: Process This document describes instruments and attributes for common OS process level metrics in OpenTelemetry. Also consider the [general metric semantic -conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions) when creating +conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in this document. OS process metrics are not related to the runtime environment of the program, and should take measurements from the operating system. For runtime environment metrics see @@ -31,7 +31,7 @@ metrics](runtime-environment-metrics.md). Below is a table of Process metric instruments. -| Name | Instrument Type ([\*](/specification/general/metrics-general.md#instrument-types)) | Unit | Description | Labels | +| Name | Instrument Type ([\*](/docs/general/metrics-general.md#instrument-types)) | Unit | Description | Labels | |---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | | `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | @@ -46,6 +46,6 @@ Below is a table of Process metric instruments. ## Attributes -Process metrics SHOULD be associated with a [`process`](/specification/resource/process.md#process) resource whose attributes provide additional context about the process. +Process metrics SHOULD be associated with a [`process`](/docs/resource/process.md#process) resource whose attributes provide additional context about the process. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md similarity index 98% rename from specification/system/runtime-environment-metrics.md rename to docs/system/runtime-environment-metrics.md index 114c5b4b06..d28c355e90 100644 --- a/specification/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -8,7 +8,7 @@ linkTitle: Runtime Environment This document includes semantic conventions for runtime environment level metrics in OpenTelemetry. Also consider the [general -metric](/specification/general/metrics-general.md#general-metric-semantic-conventions), [system +metric](/docs/general/metrics-general.md#general-metric-semantic-conventions), [system metrics](system-metrics.md) and [OS Process metrics](process-metrics.md) semantic conventions when instrumenting runtime environments. @@ -56,7 +56,7 @@ discussion. Metrics specific to a certain runtime environment should be prefixed with `process.runtime.{environment}.` and follow the semantic conventions outlined in [general metric semantic -conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions). Authors of +conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions). Authors of runtime instrumentations are responsible for the choice of `{environment}` to avoid ambiguity when interpreting a metric's name or values. @@ -71,7 +71,7 @@ consider, for example pthreads vs green thread implementations. ## Attributes -[`process.runtime`](/specification/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. +[`process.runtime`](/docs/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. ## JVM Metrics diff --git a/specification/system/system-metrics.md b/docs/system/system-metrics.md similarity index 93% rename from specification/system/system-metrics.md rename to docs/system/system-metrics.md index 9b5eefe328..8aef8ad299 100644 --- a/specification/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -8,7 +8,7 @@ linkTitle: System This document describes instruments and attributes for common system level metrics in OpenTelemetry. Consider the [general metric semantic -conventions](/specification/general/metrics-general.md#general-metric-semantic-conventions) when creating +conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. @@ -33,7 +33,7 @@ instruments not explicitly defined in the specification. **Description:** System level processor metrics. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | | system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. | | | | | | | cpu | CPU number [0..n-1] | @@ -45,7 +45,7 @@ instruments not explicitly defined in the specification. **Description:** System level memory metrics. This does not include [paging/swap memory](#systempaging---pagingswap-metrics). -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | ------------------------ | | system.memory.usage | | By | UpDownCounter | Int64 | state | used, free, cached, etc. | | system.memory.utilization | | 1 | Gauge | Double | state | used, free, cached, etc. | @@ -54,7 +54,7 @@ memory](#systempaging---pagingswap-metrics). **Description:** System level paging/swap memory metrics. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | |---------------------------|-------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| | system.paging.usage | Unix swap or windows pagefile usage | By | UpDownCounter | Int64 | state | used, free | | system.paging.utilization | | 1 | Gauge | Double | state | used, free | @@ -66,7 +66,7 @@ memory](#systempaging---pagingswap-metrics). **Description:** System level disk performance metrics. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | |--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| | system.disk.io | | By | Counter | Int64 | device | (identifier) | | | | | | | direction | read, write | @@ -101,7 +101,7 @@ perf counter (similar for Writes) **Description:** System level filesystem metrics. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | -------------------- | | system.filesystem.usage | | By | UpDownCounter | Int64 | device | (identifier) | | | | | | | state | used, free, reserved | @@ -118,7 +118,7 @@ perf counter (similar for Writes) **Description:** System level network metrics. -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | |----------------------------------------|-------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packet} | Counter | Int64 | device | (identifier) | | | | | | | direction | transmit, receive | @@ -155,7 +155,7 @@ from **Description:** System level aggregate process metrics. For metrics at the individual process level, see [process metrics](process-metrics.md). -| Name | Description | Units | Instrument Type ([*](/specification/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | | system.processes.count | Total number of processes in each state | {process} | UpDownCounter | Int64 | status | running, sleeping, [etc.](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | | system.processes.created | Total number of processes created over uptime of the host | {process} | Counter | Int64 | - | - | diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index ef66661b53..434b078228 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -22,7 +22,7 @@ fix_file() { "$1" } -important_files=("specification" "semantic_conventions" "README.md" "supplementary-guidelines") +important_files=("specification" "model" "README.md" "supplementary-guidelines") # TODO - limit to markdown/yaml files? find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do diff --git a/semantic_conventions/README.md b/model/README.md similarity index 96% rename from semantic_conventions/README.md rename to model/README.md index 3c42e73d0b..6c0461484b 100644 --- a/semantic_conventions/README.md +++ b/model/README.md @@ -5,7 +5,7 @@ be used by the various OpenTelemetry language implementations to aid in automati generation of semantics-related code. ⚠ If you want to read the semantic conventions and not edit them, please see -the generated markdown output in the [specification](../specification/README.md) folder. +the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions diff --git a/semantic_conventions/client.yaml b/model/client.yaml similarity index 100% rename from semantic_conventions/client.yaml rename to model/client.yaml diff --git a/semantic_conventions/deprecated/http.yaml b/model/deprecated/http.yaml similarity index 100% rename from semantic_conventions/deprecated/http.yaml rename to model/deprecated/http.yaml diff --git a/semantic_conventions/deprecated/network.yaml b/model/deprecated/network.yaml similarity index 100% rename from semantic_conventions/deprecated/network.yaml rename to model/deprecated/network.yaml diff --git a/semantic_conventions/destination.yaml b/model/destination.yaml similarity index 100% rename from semantic_conventions/destination.yaml rename to model/destination.yaml diff --git a/semantic_conventions/exception.yaml b/model/exception.yaml similarity index 100% rename from semantic_conventions/exception.yaml rename to model/exception.yaml diff --git a/semantic_conventions/http-common.yaml b/model/http-common.yaml similarity index 93% rename from semantic_conventions/http-common.yaml rename to model/http-common.yaml index 5f7fdd58f6..682b2cb984 100644 --- a/semantic_conventions/http-common.yaml +++ b/model/http-common.yaml @@ -111,14 +111,14 @@ groups: note: > 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](/specification/http/http-spans.md#http-server-definitions) if there is one. + SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - ref: server.address brief: > Name of the local HTTP server that received the request. note: | Determined by using the first of the following that applies - - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only + - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -132,7 +132,7 @@ groups: note: | Determined by using the first of the following that applies - - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. + - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header diff --git a/semantic_conventions/logs/events.yaml b/model/logs/events.yaml similarity index 100% rename from semantic_conventions/logs/events.yaml rename to model/logs/events.yaml diff --git a/semantic_conventions/logs/general.yaml b/model/logs/general.yaml similarity index 100% rename from semantic_conventions/logs/general.yaml rename to model/logs/general.yaml diff --git a/semantic_conventions/logs/log-exception.yaml b/model/logs/log-exception.yaml similarity index 100% rename from semantic_conventions/logs/log-exception.yaml rename to model/logs/log-exception.yaml diff --git a/semantic_conventions/logs/log-feature_flag.yaml b/model/logs/log-feature_flag.yaml similarity index 100% rename from semantic_conventions/logs/log-feature_flag.yaml rename to model/logs/log-feature_flag.yaml diff --git a/semantic_conventions/logs/media.yaml b/model/logs/media.yaml similarity index 100% rename from semantic_conventions/logs/media.yaml rename to model/logs/media.yaml diff --git a/semantic_conventions/metrics/http.yaml b/model/metrics/http.yaml similarity index 89% rename from semantic_conventions/metrics/http.yaml rename to model/metrics/http.yaml index cb39118bd6..385242ddbb 100644 --- a/semantic_conventions/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -11,7 +11,7 @@ groups: note: | Determined by using the first of the following that applies - - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only + - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -26,7 +26,7 @@ groups: note: | Determined by using the first of the following that applies - - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. + - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header @@ -74,7 +74,7 @@ groups: note: | Determined by using the first of the following that applies - - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only + - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -89,7 +89,7 @@ groups: note: | Determined by using the first of the following that applies - - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. + - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header diff --git a/semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/process-runtime-jvm-metrics-experimental.yaml similarity index 100% rename from semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml rename to model/metrics/process-runtime-jvm-metrics-experimental.yaml diff --git a/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/process-runtime-jvm-metrics.yaml similarity index 100% rename from semantic_conventions/metrics/process-runtime-jvm-metrics.yaml rename to model/metrics/process-runtime-jvm-metrics.yaml diff --git a/semantic_conventions/resource/browser.yaml b/model/resource/browser.yaml similarity index 100% rename from semantic_conventions/resource/browser.yaml rename to model/resource/browser.yaml diff --git a/semantic_conventions/resource/cloud.yaml b/model/resource/cloud.yaml similarity index 100% rename from semantic_conventions/resource/cloud.yaml rename to model/resource/cloud.yaml diff --git a/semantic_conventions/resource/cloud_provider/aws/ecs.yaml b/model/resource/cloud_provider/aws/ecs.yaml similarity index 100% rename from semantic_conventions/resource/cloud_provider/aws/ecs.yaml rename to model/resource/cloud_provider/aws/ecs.yaml diff --git a/semantic_conventions/resource/cloud_provider/aws/eks.yaml b/model/resource/cloud_provider/aws/eks.yaml similarity index 100% rename from semantic_conventions/resource/cloud_provider/aws/eks.yaml rename to model/resource/cloud_provider/aws/eks.yaml diff --git a/semantic_conventions/resource/cloud_provider/aws/logs.yaml b/model/resource/cloud_provider/aws/logs.yaml similarity index 100% rename from semantic_conventions/resource/cloud_provider/aws/logs.yaml rename to model/resource/cloud_provider/aws/logs.yaml diff --git a/semantic_conventions/resource/cloud_provider/gcp/cloud_run.yaml b/model/resource/cloud_provider/gcp/cloud_run.yaml similarity index 100% rename from semantic_conventions/resource/cloud_provider/gcp/cloud_run.yaml rename to model/resource/cloud_provider/gcp/cloud_run.yaml diff --git a/semantic_conventions/resource/cloud_provider/gcp/gce.yaml b/model/resource/cloud_provider/gcp/gce.yaml similarity index 100% rename from semantic_conventions/resource/cloud_provider/gcp/gce.yaml rename to model/resource/cloud_provider/gcp/gce.yaml diff --git a/semantic_conventions/resource/cloud_provider/heroku.yaml b/model/resource/cloud_provider/heroku.yaml similarity index 100% rename from semantic_conventions/resource/cloud_provider/heroku.yaml rename to model/resource/cloud_provider/heroku.yaml diff --git a/semantic_conventions/resource/container.yaml b/model/resource/container.yaml similarity index 100% rename from semantic_conventions/resource/container.yaml rename to model/resource/container.yaml diff --git a/semantic_conventions/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml similarity index 100% rename from semantic_conventions/resource/deployment_environment.yaml rename to model/resource/deployment_environment.yaml diff --git a/semantic_conventions/resource/device.yaml b/model/resource/device.yaml similarity index 100% rename from semantic_conventions/resource/device.yaml rename to model/resource/device.yaml diff --git a/semantic_conventions/resource/faas.yaml b/model/resource/faas.yaml similarity index 96% rename from semantic_conventions/resource/faas.yaml rename to model/resource/faas.yaml index f6e4b949a3..cf226889ac 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/model/resource/faas.yaml @@ -14,7 +14,7 @@ groups: This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback function (which may be stored in the - [`code.namespace`/`code.function`](/specification/general/general-attributes.md#source-code-attributes) + [`code.namespace`/`code.function`](/docs/general/general-attributes.md#source-code-attributes) span attributes). For some cloud providers, the above definition is ambiguous. The following diff --git a/semantic_conventions/resource/host.yaml b/model/resource/host.yaml similarity index 100% rename from semantic_conventions/resource/host.yaml rename to model/resource/host.yaml diff --git a/semantic_conventions/resource/k8s.yaml b/model/resource/k8s.yaml similarity index 100% rename from semantic_conventions/resource/k8s.yaml rename to model/resource/k8s.yaml diff --git a/semantic_conventions/resource/os.yaml b/model/resource/os.yaml similarity index 96% rename from semantic_conventions/resource/os.yaml rename to model/resource/os.yaml index c1b8c7ef9d..083b88495e 100644 --- a/semantic_conventions/resource/os.yaml +++ b/model/resource/os.yaml @@ -61,5 +61,5 @@ groups: type: string brief: > The version string of the operating system as defined in - [Version Attributes](/specification/resource/README.md#version-attributes). + [Version Attributes](/docs/resource/README.md#version-attributes). examples: ['14.2.1', '18.04.1'] diff --git a/semantic_conventions/resource/process.yaml b/model/resource/process.yaml similarity index 100% rename from semantic_conventions/resource/process.yaml rename to model/resource/process.yaml diff --git a/semantic_conventions/resource/service.yaml b/model/resource/service.yaml similarity index 100% rename from semantic_conventions/resource/service.yaml rename to model/resource/service.yaml diff --git a/semantic_conventions/resource/service_experimental.yaml b/model/resource/service_experimental.yaml similarity index 100% rename from semantic_conventions/resource/service_experimental.yaml rename to model/resource/service_experimental.yaml diff --git a/semantic_conventions/resource/telemetry.yaml b/model/resource/telemetry.yaml similarity index 100% rename from semantic_conventions/resource/telemetry.yaml rename to model/resource/telemetry.yaml diff --git a/semantic_conventions/resource/telemetry_experimental.yaml b/model/resource/telemetry_experimental.yaml similarity index 100% rename from semantic_conventions/resource/telemetry_experimental.yaml rename to model/resource/telemetry_experimental.yaml diff --git a/semantic_conventions/resource/webengine.yaml b/model/resource/webengine.yaml similarity index 100% rename from semantic_conventions/resource/webengine.yaml rename to model/resource/webengine.yaml diff --git a/semantic_conventions/scope/exporter/exporter.yaml b/model/scope/exporter/exporter.yaml similarity index 100% rename from semantic_conventions/scope/exporter/exporter.yaml rename to model/scope/exporter/exporter.yaml diff --git a/semantic_conventions/server.yaml b/model/server.yaml similarity index 100% rename from semantic_conventions/server.yaml rename to model/server.yaml diff --git a/semantic_conventions/source.yaml b/model/source.yaml similarity index 100% rename from semantic_conventions/source.yaml rename to model/source.yaml diff --git a/semantic_conventions/trace/aws/lambda.yaml b/model/trace/aws/lambda.yaml similarity index 100% rename from semantic_conventions/trace/aws/lambda.yaml rename to model/trace/aws/lambda.yaml diff --git a/semantic_conventions/trace/cloudevents.yaml b/model/trace/cloudevents.yaml similarity index 100% rename from semantic_conventions/trace/cloudevents.yaml rename to model/trace/cloudevents.yaml diff --git a/semantic_conventions/trace/compatibility.yaml b/model/trace/compatibility.yaml similarity index 100% rename from semantic_conventions/trace/compatibility.yaml rename to model/trace/compatibility.yaml diff --git a/semantic_conventions/trace/database.yaml b/model/trace/database.yaml similarity index 100% rename from semantic_conventions/trace/database.yaml rename to model/trace/database.yaml diff --git a/semantic_conventions/trace/exporter/exporter.yaml b/model/trace/exporter/exporter.yaml similarity index 100% rename from semantic_conventions/trace/exporter/exporter.yaml rename to model/trace/exporter/exporter.yaml diff --git a/semantic_conventions/trace/faas.yaml b/model/trace/faas.yaml similarity index 100% rename from semantic_conventions/trace/faas.yaml rename to model/trace/faas.yaml diff --git a/semantic_conventions/trace/feature-flag.yaml b/model/trace/feature-flag.yaml similarity index 100% rename from semantic_conventions/trace/feature-flag.yaml rename to model/trace/feature-flag.yaml diff --git a/semantic_conventions/trace/general.yaml b/model/trace/general.yaml similarity index 99% rename from semantic_conventions/trace/general.yaml rename to model/trace/general.yaml index fd1e3136d1..545bce5cab 100644 --- a/semantic_conventions/trace/general.yaml +++ b/model/trace/general.yaml @@ -170,7 +170,7 @@ groups: - id: service type: string brief: > - The [`service.name`](/specification/resource/README.md#service) + The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. examples: "AuthTokenCache" diff --git a/semantic_conventions/trace/http.yaml b/model/trace/http.yaml similarity index 96% rename from semantic_conventions/trace/http.yaml rename to model/trace/http.yaml index 65f53216e6..53898fb483 100644 --- a/semantic_conventions/trace/http.yaml +++ b/model/trace/http.yaml @@ -100,7 +100,7 @@ groups: note: | Determined by using the first of the following that applies - - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only + - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -116,7 +116,7 @@ groups: note: | Determined by using the first of the following that applies - - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. + - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header diff --git a/semantic_conventions/trace/instrumentation/aws-sdk.yml b/model/trace/instrumentation/aws-sdk.yml similarity index 100% rename from semantic_conventions/trace/instrumentation/aws-sdk.yml rename to model/trace/instrumentation/aws-sdk.yml diff --git a/semantic_conventions/trace/instrumentation/graphql.yml b/model/trace/instrumentation/graphql.yml similarity index 100% rename from semantic_conventions/trace/instrumentation/graphql.yml rename to model/trace/instrumentation/graphql.yml diff --git a/semantic_conventions/trace/messaging.yaml b/model/trace/messaging.yaml similarity index 100% rename from semantic_conventions/trace/messaging.yaml rename to model/trace/messaging.yaml diff --git a/semantic_conventions/trace/rpc.yaml b/model/trace/rpc.yaml similarity index 100% rename from semantic_conventions/trace/rpc.yaml rename to model/trace/rpc.yaml diff --git a/semantic_conventions/trace/trace-exception.yaml b/model/trace/trace-exception.yaml similarity index 100% rename from semantic_conventions/trace/trace-exception.yaml rename to model/trace/trace-exception.yaml diff --git a/semantic_conventions/url.yaml b/model/url.yaml similarity index 100% rename from semantic_conventions/url.yaml rename to model/url.yaml diff --git a/semantic_conventions/user-agent.yaml b/model/user-agent.yaml similarity index 100% rename from semantic_conventions/user-agent.yaml rename to model/user-agent.yaml diff --git a/semantic_conventions/version.properties b/model/version.properties similarity index 100% rename from semantic_conventions/version.properties rename to model/version.properties diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index 9f939bcffb..db8086066f 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -38,5 +38,5 @@ The following formats are currently natively supported by AWS services for propa AWS service-supported context propagation is necessary to allow context propagation through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`. -(See the [aws-lambda sqs-event semantic convention](../../specification/faas/aws-lambda.md#sqs-event) +(See the [aws-lambda sqs-event semantic convention](/docs/faas/aws-lambda.md#sqs-event) doc for details on how this context propagation is consumed by Lambda instrumentation.) From 053fe9ade0fb4144778222c344a4e82f9fdcb707 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 7 Jul 2023 14:31:58 +0200 Subject: [PATCH 07/44] Fix path of md table generation make task (#173) --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index b02fdc0952..bcd7f57682 100644 --- a/Makefile +++ b/Makefile @@ -74,13 +74,13 @@ yamllint: # Generate markdown tables from YAML definitions .PHONY: table-generation table-generation: - docker run --rm -v $(PWD)/model:/source -v $(PWD)/specification:/spec \ + docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec # Check if current markdown tables differ from the ones that would be generated from YAML definitions .PHONY: table-check table-check: - docker run --rm -v $(PWD)/model:/source -v $(PWD)/specification:/spec \ + docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check .PHONY: schema-check From 86940d241f0e56e3662ace425664abcc3b1b6d49 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Fri, 7 Jul 2023 17:29:21 +0300 Subject: [PATCH 08/44] Add markdown file for url semantic conventions (#174) --- CHANGELOG.md | 2 ++ docs/database/elasticsearch.md | 2 +- docs/http/http-metrics.md | 8 +++--- docs/http/http-spans.md | 16 ++++++------ docs/url/README.md | 11 ++++++++ docs/url/url.md | 47 ++++++++++++++++++++++++++++++++++ 6 files changed, 73 insertions(+), 13 deletions(-) create mode 100644 docs/url/README.md create mode 100644 docs/url/url.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c9576b4f9..9a8cf30653 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -107,6 +107,8 @@ Note: This is the first release of Semantic Conventions separate from the Specif ([#23](https://github.com/open-telemetry/semantic-conventions/pull/23)) - Add YAML definitions for log semantic conventions and define requirement levels ([#133](https://github.com/open-telemetry/semantic-conventions/pull/133)) +- Add markdown file for url semantic conventions + ([#174](https://github.com/open-telemetry/semantic-conventions/pull/174)) ## v1.20.0 (2023-04-07) diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 5f1734dbfd..3a5c6bcaf5 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -38,7 +38,7 @@ in order to map the path part values to their names. | `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | [`server.address`](../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below | | [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | -| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** 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. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 43b37ace2b..c4b7231803 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -81,7 +81,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | | [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. @@ -155,7 +155,7 @@ This metric is optional. | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | | [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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) @@ -228,7 +228,7 @@ This metric is optional. | [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | | [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. @@ -306,7 +306,7 @@ This metric is optional. | [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | | [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 553fdbf938..0be977dba8 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -198,7 +198,7 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. | | [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | -| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | **[1]:** 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). @@ -225,7 +225,7 @@ Following attributes MUST be provided **at span creation time** (when provided a * [`server.address`](../general/general-attributes.md) * [`server.port`](../general/general-attributes.md) -* `url.full` +* [`url.full`](../url/url.md) Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. @@ -331,9 +331,9 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | | [`server.socket.address`](../general/general-attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | | [`server.socket.port`](../general/general-attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | -| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | -| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | +| [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. @@ -369,9 +369,9 @@ Following attributes MUST be provided **at span creation time** (when provided a * [`server.address`](../general/general-attributes.md) * [`server.port`](../general/general-attributes.md) -* `url.path` -* `url.query` -* `url.scheme` +* [`url.path`](../url/url.md) +* [`url.query`](../url/url.md) +* [`url.scheme`](../url/url.md) `http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. diff --git a/docs/url/README.md b/docs/url/README.md new file mode 100644 index 0000000000..f3e3dc7c2c --- /dev/null +++ b/docs/url/README.md @@ -0,0 +1,11 @@ +# URL semantic conventions + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for URLs. + +URL semantic conventions are defined for the following: + +* [URL](url.md): For describing URL and its components. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/docs/url/url.md b/docs/url/url.md new file mode 100644 index 0000000000..99ba2af01c --- /dev/null +++ b/docs/url/url.md @@ -0,0 +1,47 @@ +# Semantic conventions for URL + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions that describe URL and its components. + +
+Table of Contents + + + +- [Attributes](#attributes) +- [Sensitive information](#sensitive-information) + + + +
+ +## Attributes + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | +| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | +| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | +| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended | +| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | + +**[1]:** 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. + +**[2]:** When missing, the value is assumed to be `/` + +**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + + +## Sensitive information + +Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded. + +Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties. + +_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._ + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md From c2b9767adc4910638e38711a7799d0defa5b87fd Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Jul 2023 10:33:59 -0400 Subject: [PATCH 09/44] [editorial] Add missing `README.md` for Resource Cloud Provider semconv (#171) Co-authored-by: Joao Grassi Co-authored-by: Armin Ruech --- docs/resource/cloud_provider/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/resource/cloud_provider/README.md diff --git a/docs/resource/cloud_provider/README.md b/docs/resource/cloud_provider/README.md new file mode 100644 index 0000000000..40b11dc068 --- /dev/null +++ b/docs/resource/cloud_provider/README.md @@ -0,0 +1,15 @@ + + +# Resource Cloud Provider Semantic Conventions + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for resource cloud providers. + +* [AWS](aws/README.md): Semantic Conventions for Amazon Web Services. +* [GCP](gcp/README.md): Semantic Conventions for Google Cloud Platform. +* [Heroku](heroku.md): Semantic Conventions for Heroku. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md From 02071de4bef12de6e0a0ae199e5251d35b69dec9 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Jul 2023 10:53:29 -0400 Subject: [PATCH 10/44] [editorial] docs/rpc/json-rpc: fix title and in-page hypenation (#170) Co-authored-by: Armin Ruech --- docs/rpc/json-rpc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 72d4a1beff..b87b888b62 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -1,4 +1,4 @@ -# Semantic Conventions for gRPC +# Semantic Conventions for JSON-RPC **Status**: [Experimental][DocumentStatus] @@ -6,7 +6,7 @@ The Semantic Conventions for [JSON-RPC](https://www.jsonrpc.org/) extend and ove that describe common RPC operations attributes in addition to the Semantic Conventions described on this page. -## JSON RPC Attributes +## JSON-RPC Attributes `rpc.system` MUST be set to `"jsonrpc"`. From 57bd0117fc17e8f36f402a397027e648d113ce3c Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Jul 2023 11:05:54 -0400 Subject: [PATCH 11/44] [editorial] Rename docs files and folders: replace "_" by "-"; add check (#177) Co-authored-by: Armin Ruech --- .github/workflows/checks.yml | 3 +++ Makefile | 12 +++++++++++- docs/resource/README.md | 10 +++++----- .../{cloud_provider => cloud-provider}/README.md | 0 .../{cloud_provider => cloud-provider}/aws/README.md | 0 .../{cloud_provider => cloud-provider}/aws/ecs.md | 0 .../{cloud_provider => cloud-provider}/aws/eks.md | 0 .../{cloud_provider => cloud-provider}/aws/logs.md | 0 .../{cloud_provider => cloud-provider}/gcp/README.md | 2 +- .../cloud_run.md => cloud-provider/gcp/cloud-run.md} | 0 .../{cloud_provider => cloud-provider}/gcp/gce.md | 0 .../{cloud_provider => cloud-provider}/heroku.md | 0 ...ment_environment.md => deployment-environment.md} | 0 13 files changed, 20 insertions(+), 7 deletions(-) rename docs/resource/{cloud_provider => cloud-provider}/README.md (100%) rename docs/resource/{cloud_provider => cloud-provider}/aws/README.md (100%) rename docs/resource/{cloud_provider => cloud-provider}/aws/ecs.md (100%) rename docs/resource/{cloud_provider => cloud-provider}/aws/eks.md (100%) rename docs/resource/{cloud_provider => cloud-provider}/aws/logs.md (100%) rename docs/resource/{cloud_provider => cloud-provider}/gcp/README.md (94%) rename docs/resource/{cloud_provider/gcp/cloud_run.md => cloud-provider/gcp/cloud-run.md} (100%) rename docs/resource/{cloud_provider => cloud-provider}/gcp/gce.md (100%) rename docs/resource/{cloud_provider => cloud-provider}/heroku.md (100%) rename docs/resource/{deployment_environment.md => deployment-environment.md} (100%) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index df8d785371..9c94e529c7 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -16,6 +16,9 @@ jobs: - name: install dependencies run: npm install + - name: Check file and folder names + run: make check-file-and-folder-names-in-docs + - name: run markdownlint run: make markdownlint diff --git a/Makefile b/Makefile index bcd7f57682..1375040f7a 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,17 @@ SEMCONVGEN_VERSION=0.18.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all -all: install-tools markdownlint markdown-link-check misspell table-check schema-check +all: install-tools markdownlint markdown-link-check misspell table-check schema-check \ + check-file-and-folder-names-in-docs + +.PHONY: check-file-and-folder-names-in-docs +check-file-and-folder-names-in-docs: + @found=`find docs -name '*_*'`; \ + if [ -n "$$found" ]; then \ + echo "Error: Underscores found in doc file or folder names, use hyphens instead:"; \ + echo $$found; \ + exit 1; \ + fi $(MISSPELL): cd $(TOOLS_DIR) && go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell diff --git a/docs/resource/README.md b/docs/resource/README.md index 4be3ec3868..3ab4e9c9ac 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -198,7 +198,7 @@ Attributes defining a running environment (e.g. Operating System, Cloud, Data Ce - [Device](./device.md) - [Cloud](./cloud.md) - Deployment: - - [Deployment Environment](./deployment_environment.md) + - [Deployment Environment](./deployment-environment.md) - [Kubernetes](./k8s.md) - [Browser](./browser.md) @@ -216,14 +216,14 @@ the exact version used to identify an artifact. This may be a semantic version, Attributes that are only applicable to resources from a specific cloud provider. Currently, these resources can only be defined for providers listed as a valid `cloud.provider` in -[Cloud](./cloud.md) and below. Provider-specific attributes all reside in the `cloud_provider` directory. +[Cloud](./cloud.md) and below. Provider-specific attributes all reside in the `cloud-provider` directory. Valid cloud providers are: - [Alibaba Cloud](https://www.alibabacloud.com/) (`alibaba_cloud`) -- [Amazon Web Services](https://aws.amazon.com/) ([`aws`](cloud_provider/aws/README.md)) -- [Google Cloud Platform](https://cloud.google.com/) ([`gcp`](cloud_provider/gcp/README.md)) +- [Amazon Web Services](https://aws.amazon.com/) ([`aws`](cloud-provider/aws/README.md)) +- [Google Cloud Platform](https://cloud.google.com/) ([`gcp`](cloud-provider/gcp/README.md)) - [Microsoft Azure](https://azure.microsoft.com/) (`azure`) - [Tencent Cloud](https://www.tencentcloud.com/) (`tencent_cloud`) -- [Heroku dyno](./cloud_provider/heroku.md) +- [Heroku dyno](./cloud-provider/heroku.md) [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/docs/resource/cloud_provider/README.md b/docs/resource/cloud-provider/README.md similarity index 100% rename from docs/resource/cloud_provider/README.md rename to docs/resource/cloud-provider/README.md diff --git a/docs/resource/cloud_provider/aws/README.md b/docs/resource/cloud-provider/aws/README.md similarity index 100% rename from docs/resource/cloud_provider/aws/README.md rename to docs/resource/cloud-provider/aws/README.md diff --git a/docs/resource/cloud_provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md similarity index 100% rename from docs/resource/cloud_provider/aws/ecs.md rename to docs/resource/cloud-provider/aws/ecs.md diff --git a/docs/resource/cloud_provider/aws/eks.md b/docs/resource/cloud-provider/aws/eks.md similarity index 100% rename from docs/resource/cloud_provider/aws/eks.md rename to docs/resource/cloud-provider/aws/eks.md diff --git a/docs/resource/cloud_provider/aws/logs.md b/docs/resource/cloud-provider/aws/logs.md similarity index 100% rename from docs/resource/cloud_provider/aws/logs.md rename to docs/resource/cloud-provider/aws/logs.md diff --git a/docs/resource/cloud_provider/gcp/README.md b/docs/resource/cloud-provider/gcp/README.md similarity index 94% rename from docs/resource/cloud_provider/gcp/README.md rename to docs/resource/cloud-provider/gcp/README.md index 97426ae20b..6bf3a4a150 100644 --- a/docs/resource/cloud_provider/gcp/README.md +++ b/docs/resource/cloud-provider/gcp/README.md @@ -9,7 +9,7 @@ provider (like account ID, operating system, etc), it belongs in the parent ## Services -- [Cloud Run](./cloud_run.md) +- [Cloud Run](./cloud-run.md) - [Compute Engine](./gce.md) [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/docs/resource/cloud_provider/gcp/cloud_run.md b/docs/resource/cloud-provider/gcp/cloud-run.md similarity index 100% rename from docs/resource/cloud_provider/gcp/cloud_run.md rename to docs/resource/cloud-provider/gcp/cloud-run.md diff --git a/docs/resource/cloud_provider/gcp/gce.md b/docs/resource/cloud-provider/gcp/gce.md similarity index 100% rename from docs/resource/cloud_provider/gcp/gce.md rename to docs/resource/cloud-provider/gcp/gce.md diff --git a/docs/resource/cloud_provider/heroku.md b/docs/resource/cloud-provider/heroku.md similarity index 100% rename from docs/resource/cloud_provider/heroku.md rename to docs/resource/cloud-provider/heroku.md diff --git a/docs/resource/deployment_environment.md b/docs/resource/deployment-environment.md similarity index 100% rename from docs/resource/deployment_environment.md rename to docs/resource/deployment-environment.md From c35b1d4ca60f8a5ede939b030e35e433925cfd13 Mon Sep 17 00:00:00 2001 From: YANGDB Date: Fri, 7 Jul 2023 12:08:43 -0700 Subject: [PATCH 12/44] Fix semantic-conventions README.md file links (#168) Signed-off-by: YANGDB Co-authored-by: Josh Suereth --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index fe9c908ff0..cc7f94966a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,8 +12,8 @@ Semantic Conventions are defined for the following areas: * [Database](database/README.md): Semantic Conventions for database operations. * [Exceptions](exceptions/README.md): Semantic Conventions for exceptions. * [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. -* [Feature Flags](http/README.md): Semantic Conventions for feature flag evaluations. -* [HTTP](feature-flags/README.md): Semantic Conventions for HTTP client and server operations. +* [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations. +* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. * [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems. * [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations. * [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations. From aa85e62c40b808815d9540fa3959d466ca27fa73 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Jul 2023 18:53:22 -0400 Subject: [PATCH 13/44] [editorial] Fix doc page titles and add Hugo front matter (#175) --- docs/README.md | 16 +++++++++++++++- docs/cloud-providers/README.md | 9 ++++++++- docs/cloud-providers/aws-sdk.md | 6 +++++- docs/cloudevents/README.md | 9 ++++++++- docs/cloudevents/cloudevents-spans.md | 6 +++++- docs/database/README.md | 9 ++++++++- docs/database/cassandra.md | 4 ++++ docs/database/cosmosdb.md | 4 ++++ docs/database/couchdb.md | 4 ++++ docs/database/database-metrics.md | 2 +- docs/database/database-spans.md | 6 +++++- docs/database/dynamodb.md | 4 ++++ docs/database/elasticsearch.md | 6 +++++- docs/database/graphql.md | 6 +++++- docs/database/hbase.md | 4 ++++ docs/database/mongodb.md | 4 ++++ docs/database/mssql.md | 4 ++++ docs/database/redis.md | 4 ++++ docs/database/sql.md | 6 +++++- docs/exceptions/README.md | 9 ++++++++- docs/exceptions/exceptions-logs.md | 4 ++++ docs/exceptions/exceptions-spans.md | 4 ++++ docs/faas/README.md | 9 ++++++++- docs/faas/faas-metrics.md | 2 +- docs/faas/faas-spans.md | 6 +++++- docs/feature-flags/README.md | 9 ++++++++- docs/feature-flags/feature-flags-logs.md | 4 ++++ docs/feature-flags/feature-flags-spans.md | 6 +++++- docs/general/README.md | 8 ++++++++ docs/general/events-general.md | 6 +++++- docs/general/general-attributes.md | 6 +++++- docs/general/logs-general.md | 6 +++++- docs/general/metrics-general.md | 4 ++++ docs/general/trace-compatibility.md | 6 +++++- docs/general/trace-general.md | 4 ++++ docs/http/README.md | 9 ++++++++- docs/http/http-metrics.md | 2 +- docs/http/http-spans.md | 6 +++++- docs/messaging/README.md | 9 ++++++++- docs/messaging/messaging-spans.md | 2 +- docs/messaging/rabbitmq.md | 4 ++++ docs/messaging/rocketmq.md | 4 ++++ docs/object-stores/README.md | 9 ++++++++- docs/object-stores/s3.md | 4 ++++ docs/resource/README.md | 7 +++++++ docs/resource/cloud-provider/README.md | 5 ++++- docs/resource/cloud-provider/aws/README.md | 7 +++++++ docs/resource/cloud-provider/gcp/README.md | 7 +++++++ docs/resource/process.md | 2 +- docs/rpc/README.md | 9 ++++++++- docs/rpc/connect-rpc.md | 4 ++++ docs/rpc/grpc.md | 4 ++++ docs/rpc/json-rpc.md | 4 ++++ docs/rpc/rpc-metrics.md | 4 ++-- docs/rpc/rpc-spans.md | 6 +++++- docs/system/README.md | 9 ++++++++- docs/url/README.md | 9 ++++++++- docs/url/url.md | 6 +++++- 58 files changed, 302 insertions(+), 36 deletions(-) diff --git a/docs/README.md b/docs/README.md index cc7f94966a..9cfd635f66 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,17 @@ + + # OpenTelemetry Semantic Conventions The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it. @@ -7,8 +21,8 @@ The benefit to using Semantic Conventions is in following a common naming scheme Semantic Conventions are defined for the following areas: * **[General](general/README.md): General Semantic Conventions**. -* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. * [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries. +* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. * [Database](database/README.md): Semantic Conventions for database operations. * [Exceptions](exceptions/README.md): Semantic Conventions for exceptions. * [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. diff --git a/docs/cloud-providers/README.md b/docs/cloud-providers/README.md index effa10a97b..c9d4c89615 100644 --- a/docs/cloud-providers/README.md +++ b/docs/cloud-providers/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for cloud providers + + +# Semantic Conventions for Cloud Providers **Status**: [Experimental][DocumentStatus] diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 08e06ae87b..674ba60797 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -1,4 +1,8 @@ -# Semantic conventions for AWS SDK + + +# Semantic Conventions for AWS SDK **Status**: [Experimental][DocumentStatus] diff --git a/docs/cloudevents/README.md b/docs/cloudevents/README.md index 769151c5d5..44dcacedb8 100644 --- a/docs/cloudevents/README.md +++ b/docs/cloudevents/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for CloudEvents + + +# Semantic Conventions for CloudEvents **Status**: [Experimental][DocumentStatus] diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 830ffbd4d0..72851a62db 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -1,4 +1,8 @@ -# Semantic conventions for CloudEvents spans + + +# Semantic Conventions for CloudEvents Spans **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/README.md b/docs/database/README.md index 9d44975d32..07206bd7fc 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for database calls and systems + + +# Semantic Conventions for Database Calls and Systems **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 3468ea8f22..ef36f2e06a 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Cassandra **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 3f5f34d589..2b51f89e76 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Microsoft Cosmos DB **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 4c6411b48e..846c436b25 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for CouchDB **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index c47b82143b..1387be5792 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -1,5 +1,5 @@ # Semantic Conventions for Database Metrics diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index bae1d7e1d5..c6a8726372 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -1,4 +1,8 @@ -# Semantic conventions for database client calls + + +# Semantic Conventions for Database Client Calls **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index bc3792e66f..cd4944140b 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for AWS DynamoDB **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 3a5c6bcaf5..184397409b 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -1,4 +1,8 @@ -# Semantic conventions for Elasticsearch + + +# Semantic Conventions for Elasticsearch **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/graphql.md b/docs/database/graphql.md index 547f4b956a..f36883c8de 100644 --- a/docs/database/graphql.md +++ b/docs/database/graphql.md @@ -1,4 +1,8 @@ -# Semantic conventions for GraphQL Server + + +# Semantic Conventions for GraphQL Server **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/hbase.md b/docs/database/hbase.md index d7e77a6cc1..b1940aa479 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for HBase **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index cc81ff9276..8e69ecacad 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for MongoDB **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/mssql.md b/docs/database/mssql.md index acab76f577..2eab1fa942 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for MSSQL **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/redis.md b/docs/database/redis.md index 693e03d6ff..dc80906551 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Redis **Status**: [Experimental][DocumentStatus] diff --git a/docs/database/sql.md b/docs/database/sql.md index bf13c08103..f6cb792e23 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -1,4 +1,8 @@ -# Semantic Conventions for SQL databases + + +# Semantic Conventions for SQL Databases **Status**: [Experimental][DocumentStatus] diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index 2f0a2f9097..248f61d98b 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for Exceptions + + +# Semantic Conventions for Exceptions **Status**: [Experimental][DocumentStatus] diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index 28c26d1bb7..d9a8ef228d 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Exceptions in Logs **Status**: [Experimental][DocumentStatus] diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index 91476ab9d4..46e73db77d 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Exceptions on Spans **Status**: [Experimental][DocumentStatus] diff --git a/docs/faas/README.md b/docs/faas/README.md index f25eb48a9c..fce5377c6e 100644 --- a/docs/faas/README.md +++ b/docs/faas/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for FaaS + + +# Semantic Conventions for Function-as-a-Service **Status**: [Experimental][DocumentStatus] diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index a2958e9e66..4ec721ded0 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -1,5 +1,5 @@ # Semantic Conventions for FaaS Metrics diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 28847e3da7..ef01b86083 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -1,4 +1,8 @@ -# Semantic conventions for FaaS spans + + +# Semantic Conventions for FaaS Spans **Status**: [Experimental][DocumentStatus] diff --git a/docs/feature-flags/README.md b/docs/feature-flags/README.md index 249b82fa57..e80a9de018 100644 --- a/docs/feature-flags/README.md +++ b/docs/feature-flags/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for Feature Flags + + +# Semantic Conventions for Feature Flags **Status**: [Experimental][DocumentStatus] diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 3fc86fa2d3..71eb813cf2 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Feature Flags in Logs **Status**: [Experimental][DocumentStatus] diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md index a40a8d8cf1..72bd3ef28f 100644 --- a/docs/feature-flags/feature-flags-spans.md +++ b/docs/feature-flags/feature-flags-spans.md @@ -1,4 +1,8 @@ -# Semantic conventions for Feature Flags in Spans + + +# Semantic Conventions for Feature Flags in Spans **Status**: [Experimental][DocumentStatus] diff --git a/docs/general/README.md b/docs/general/README.md index 2a925a95bf..06f1511e40 100644 --- a/docs/general/README.md +++ b/docs/general/README.md @@ -1,3 +1,11 @@ + + # General Semantic Conventions This document defines general Semantic Conventions for spans, metrics, logs and events. diff --git a/docs/general/events-general.md b/docs/general/events-general.md index a245cbdfa0..4991f586a4 100644 --- a/docs/general/events-general.md +++ b/docs/general/events-general.md @@ -1,4 +1,8 @@ -# Semantic Convention for event attributes + + +# Semantic Conventions for Event Attributes **Status**: [Experimental][DocumentStatus] diff --git a/docs/general/general-attributes.md b/docs/general/general-attributes.md index 427cffed4b..1c031cd057 100644 --- a/docs/general/general-attributes.md +++ b/docs/general/general-attributes.md @@ -1,4 +1,8 @@ -# General attributes + + +# General Attributes **Status**: [Experimental][DocumentStatus] diff --git a/docs/general/logs-general.md b/docs/general/logs-general.md index 1cd603ca9a..22796ec2ef 100644 --- a/docs/general/logs-general.md +++ b/docs/general/logs-general.md @@ -1,4 +1,8 @@ -# General logs attributes + + +# General Logs Attributes **Status**: [Experimental][DocumentStatus] diff --git a/docs/general/metrics-general.md b/docs/general/metrics-general.md index 23135a8151..9c92afdaf4 100644 --- a/docs/general/metrics-general.md +++ b/docs/general/metrics-general.md @@ -1,3 +1,7 @@ + + # Metrics Semantic Conventions **Status**: [Mixed][DocumentStatus] diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md index 4e6d9371b7..677faf6b95 100644 --- a/docs/general/trace-compatibility.md +++ b/docs/general/trace-compatibility.md @@ -1,4 +1,8 @@ -# Semantic conventions for tracing Compatibility components + + +# Semantic Conventions for Tracing Compatibility Components **Status**: [Experimental][DocumentStatus] diff --git a/docs/general/trace-general.md b/docs/general/trace-general.md index 71d1b110d5..6a4d011715 100644 --- a/docs/general/trace-general.md +++ b/docs/general/trace-general.md @@ -1,3 +1,7 @@ + + # Trace Semantic Conventions **Status**: [Experimental][DocumentStatus] diff --git a/docs/http/README.md b/docs/http/README.md index a3ca562d5b..4b0b6c05e3 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for HTTP + + +# Semantic Conventions for HTTP **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index c4b7231803..77b062b48b 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -1,5 +1,5 @@ # Semantic Conventions for HTTP Metrics diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 0be977dba8..e333320895 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -1,4 +1,8 @@ -# Semantic conventions for HTTP spans + + +# Semantic Conventions for HTTP Spans **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/messaging/README.md b/docs/messaging/README.md index f92de2501d..46c2838bfd 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for Messaging systems + + +# Semantic Conventions for Messaging Systems **Status**: [Experimental][DocumentStatus] diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 14f63ffada..e85ea2ea23 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -1,4 +1,4 @@ -# Messaging systems +# Messaging Systems **Status**: [Experimental][DocumentStatus] diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index d3b0b3dec3..1f66215b16 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for RabbitMQ **Status**: [Experimental][DocumentStatus] diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index a758fb0c9b..35d40d2231 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for RocketMQ **Status**: [Experimental][DocumentStatus] diff --git a/docs/object-stores/README.md b/docs/object-stores/README.md index 074e0e940a..ec048f793b 100644 --- a/docs/object-stores/README.md +++ b/docs/object-stores/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for Object Stores + + +# Semantic Conventions for Object Stores **Status**: [Experimental, Feature-freeze][DocumentStatus] diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 501f07f4ba..f3ba8c4d0b 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for AWS S3 **Status**: [Experimental][DocumentStatus] diff --git a/docs/resource/README.md b/docs/resource/README.md index 3ab4e9c9ac..82433c0997 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -1,3 +1,10 @@ + + # Resource Semantic Conventions **Status**: [Mixed][DocumentStatus] diff --git a/docs/resource/cloud-provider/README.md b/docs/resource/cloud-provider/README.md index 40b11dc068..e32de4b5b3 100644 --- a/docs/resource/cloud-provider/README.md +++ b/docs/resource/cloud-provider/README.md @@ -1,5 +1,8 @@ # Resource Cloud Provider Semantic Conventions diff --git a/docs/resource/cloud-provider/aws/README.md b/docs/resource/cloud-provider/aws/README.md index 56032980ef..936d808ddc 100644 --- a/docs/resource/cloud-provider/aws/README.md +++ b/docs/resource/cloud-provider/aws/README.md @@ -1,3 +1,10 @@ + + # AWS Semantic Conventions **Status**: [Experimental][DocumentStatus] diff --git a/docs/resource/cloud-provider/gcp/README.md b/docs/resource/cloud-provider/gcp/README.md index 6bf3a4a150..ccaa39697a 100644 --- a/docs/resource/cloud-provider/gcp/README.md +++ b/docs/resource/cloud-provider/gcp/README.md @@ -1,3 +1,10 @@ + + # GCP Semantic Conventions **Status**: [Experimental][DocumentStatus] diff --git a/docs/resource/process.md b/docs/resource/process.md index b8da718e97..9b0b4a7362 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -1,4 +1,4 @@ -# Process and process runtime resources +# Process and Process Runtime Resources **Status**: [Experimental][DocumentStatus] diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 35458ce3cd..5cc1fe593c 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -1,4 +1,11 @@ -# Semantic conventions for RPC + + +# Semantic Conventions for RPC **Status**: [Experimental][DocumentStatus] diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 135c73fa2a..2e98ceba54 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for Connect RPC **Status**: [Experimental][DocumentStatus] diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 16b41f06fb..bbcb2f9932 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for gRPC **Status**: [Experimental][DocumentStatus] diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index b87b888b62..82c5461f0b 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -1,3 +1,7 @@ + + # Semantic Conventions for JSON-RPC **Status**: [Experimental][DocumentStatus] diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 7afbe316d3..49e067bbba 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -1,8 +1,8 @@ -# Semantic conventions for RPC metrics +# Semantic Conventions for RPC Metrics **Status**: [Experimental][DocumentStatus] diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 66f7c62daa..422c7768f8 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -1,4 +1,8 @@ -# Semantic conventions for RPC spans + + +# Semantic Conventions for RPC Spans **Status**: [Experimental][DocumentStatus] diff --git a/docs/system/README.md b/docs/system/README.md index d8ac2c55d5..197a616730 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -1,4 +1,11 @@ -# System semantic conventions + + +# System Semantic Conventions **Status**: [Experimental][DocumentStatus] diff --git a/docs/url/README.md b/docs/url/README.md index f3e3dc7c2c..ced1171890 100644 --- a/docs/url/README.md +++ b/docs/url/README.md @@ -1,4 +1,11 @@ -# URL semantic conventions + + +# URL Semantic Conventions **Status**: [Experimental][DocumentStatus] diff --git a/docs/url/url.md b/docs/url/url.md index 99ba2af01c..c9f0cbbbaa 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -1,4 +1,8 @@ -# Semantic conventions for URL + + +# Semantic Conventions for URL **Status**: [Experimental][DocumentStatus] From 31ca6efcf91653d7a74a52bbdf562a3719320622 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Jul 2023 19:06:07 -0400 Subject: [PATCH 14/44] [editorial] Link directly to page, not to page's title (#180) --- docs/faas/faas-spans.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index ef01b86083..31af78e346 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -36,7 +36,7 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. -If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md#function-as-a-service). +If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). | Attribute | Type | Description | Examples | Requirement Level | @@ -87,7 +87,7 @@ The following well-known definitions MUST be used if you set this attribute and ### Function Name There are 2 locations where the function's name can be recorded: the span name and the -[`faas.name` Resource attribute](../resource/faas.md#function-as-a-service). +[`faas.name` Resource attribute](../resource/faas.md). It is guaranteed that if `faas.name` attribute is present it will contain the function name, since it is defined in the semantic convention strictly for that From f875722c85cfbf60d9b0762cce76efe91607b6b7 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 12 Jul 2023 10:38:13 -0400 Subject: [PATCH 15/44] Bump to latest version of the specification. (#185) --- README.md | 2 +- docs/cloud-providers/README.md | 2 +- docs/cloud-providers/aws-sdk.md | 2 +- docs/cloudevents/README.md | 2 +- docs/cloudevents/cloudevents-spans.md | 2 +- docs/database/README.md | 2 +- docs/database/cassandra.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/couchdb.md | 2 +- docs/database/database-metrics.md | 2 +- docs/database/database-spans.md | 2 +- docs/database/dynamodb.md | 2 +- docs/database/elasticsearch.md | 2 +- docs/database/graphql.md | 2 +- docs/database/hbase.md | 2 +- docs/database/mongodb.md | 2 +- docs/database/mssql.md | 2 +- docs/database/redis.md | 2 +- docs/database/sql.md | 2 +- docs/exceptions/README.md | 2 +- docs/exceptions/exceptions-logs.md | 10 +++++----- docs/exceptions/exceptions-spans.md | 4 ++-- docs/faas/README.md | 2 +- docs/faas/aws-lambda.md | 6 +++--- docs/faas/faas-metrics.md | 2 +- docs/faas/faas-spans.md | 2 +- docs/feature-flags/README.md | 2 +- docs/feature-flags/feature-flags-logs.md | 10 +++++----- docs/feature-flags/feature-flags-spans.md | 2 +- docs/general/events-general.md | 2 +- docs/general/general-attributes.md | 2 +- docs/general/logs-general.md | 6 +++--- docs/general/metrics-general.md | 6 +++--- docs/general/trace-compatibility.md | 2 +- docs/general/trace-general.md | 2 +- docs/http/README.md | 2 +- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 6 +++--- docs/messaging/README.md | 2 +- docs/messaging/kafka.md | 2 +- docs/messaging/messaging-spans.md | 6 +++--- docs/messaging/rabbitmq.md | 2 +- docs/messaging/rocketmq.md | 2 +- docs/object-stores/README.md | 2 +- docs/object-stores/s3.md | 2 +- docs/resource/README.md | 10 +++++----- docs/resource/browser.md | 2 +- docs/resource/cloud-provider/README.md | 2 +- docs/resource/cloud-provider/aws/README.md | 2 +- docs/resource/cloud-provider/aws/ecs.md | 2 +- docs/resource/cloud-provider/aws/eks.md | 2 +- docs/resource/cloud-provider/aws/logs.md | 2 +- docs/resource/cloud-provider/gcp/README.md | 2 +- docs/resource/cloud-provider/gcp/cloud-run.md | 2 +- docs/resource/cloud-provider/heroku.md | 2 +- docs/resource/cloud.md | 2 +- docs/resource/container.md | 2 +- docs/resource/deployment-environment.md | 2 +- docs/resource/device.md | 2 +- docs/resource/faas.md | 2 +- docs/resource/host.md | 2 +- docs/resource/k8s.md | 2 +- docs/resource/os.md | 2 +- docs/resource/process.md | 2 +- docs/resource/webengine.md | 2 +- docs/rpc/README.md | 2 +- docs/rpc/connect-rpc.md | 4 ++-- docs/rpc/grpc.md | 6 +++--- docs/rpc/json-rpc.md | 2 +- docs/rpc/rpc-metrics.md | 2 +- docs/rpc/rpc-spans.md | 2 +- docs/system/README.md | 2 +- docs/system/hardware-metrics.md | 2 +- docs/system/process-metrics.md | 2 +- docs/system/runtime-environment-metrics.md | 8 ++++---- docs/system/system-metrics.md | 2 +- docs/url/README.md | 2 +- docs/url/url.md | 2 +- internal/tools/update_specification_version.sh | 6 +++--- model/README.md | 6 +++--- 80 files changed, 115 insertions(+), 115 deletions(-) diff --git a/README.md b/README.md index ef2030df3e..e528b8d2d9 100644 --- a/README.md +++ b/README.md @@ -41,4 +41,4 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs *Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).* -[SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0 +[SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0 diff --git a/docs/cloud-providers/README.md b/docs/cloud-providers/README.md index c9d4c89615..c50f4993c3 100644 --- a/docs/cloud-providers/README.md +++ b/docs/cloud-providers/README.md @@ -15,4 +15,4 @@ Semantic conventions exist for the following cloud provider SDKs: * [AWS SDK](aws-sdk.md): Semantic Conventions for the *AWS SDK*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 674ba60797..27856a3ac4 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -43,4 +43,4 @@ The following Semantic Conventions extend the general AWS SDK attributes for spe * [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*. * [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for *AWS S3*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/cloudevents/README.md b/docs/cloudevents/README.md index 44dcacedb8..4ba6cde6bb 100644 --- a/docs/cloudevents/README.md +++ b/docs/cloudevents/README.md @@ -15,4 +15,4 @@ Semantic conventions for CloudEvents are defined for the following signals: * [CloudEvents Spans](cloudevents-spans.md): Semantic Conventions for modeling CloudEvents as *spans*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 72851a62db..d2e94c847a 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -207,4 +207,4 @@ The following attributes are applicable to creation and processing Spans. | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/README.md b/docs/database/README.md index 07206bd7fc..69b0ccf1f9 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -31,4 +31,4 @@ Technology specific semantic conventions are defined for the following databases * [Redis](redis.md): Semantic Conventions for *Redis*. * [SQL](sql.md): Semantic Conventions for *SQL* databases. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index ef36f2e06a..fc420a9f5d 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -47,4 +47,4 @@ described on this page. | `local_serial` | local_serial | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 2b51f89e76..83425d15bb 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -90,4 +90,4 @@ In addition to Cosmos DB attributes, all spans include | `db.cosmosdb.sub_status_code` | `0` | | `db.cosmosdb.request_charge` | `7.43` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 846c436b25..3624e69e9c 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -22,4 +22,4 @@ described on this page. **[1]:** 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). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 1387be5792..2946857bc3 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -60,4 +60,4 @@ Below is a table of the attributes that MUST be included on all connection pool |-------------|--------|------------------------------------------------------------------------------|----------------|-------------------| | `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index c6a8726372..cb60633ca0 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -190,4 +190,4 @@ More specific Semantic Conventions are defined for the following database techno * [Redis](redis.md): Semantic Conventions for *Redis*. * [SQL](sql.md): Semantic Conventions for *SQL* databases. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index cd4944140b..f37e918366 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -170,4 +170,4 @@ These attributes are filled in for all DynamoDB request types. | `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 184397409b..bf45239383 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -83,4 +83,4 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | `url.full` | `"https://elasticsearch.mydomain.com:9200/my-index-000001/_search?from=40&size=20"` | | `db.elasticsearch.path_parts.index` | `"my-index-000001"` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/graphql.md b/docs/database/graphql.md index f36883c8de..8cc6409866 100644 --- a/docs/database/graphql.md +++ b/docs/database/graphql.md @@ -32,4 +32,4 @@ MAY be used as span name. | `subscription` | GraphQL subscription | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/hbase.md b/docs/database/hbase.md index b1940aa479..2c51ce763e 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -22,4 +22,4 @@ described on this page. **[1]:** For HBase the `db.name` should be set to the HBase namespace. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 8e69ecacad..d3d3608272 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -37,4 +37,4 @@ described on this page. | `db.operation` | `"findAndModify"` | | `db.mongodb.collection` | `"products"` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 2eab1fa942..ee1bc5e099 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -23,4 +23,4 @@ described on this page. **[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/redis.md b/docs/database/redis.md index dc80906551..f7e8d41079 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -43,4 +43,4 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an | `db.operation` | not set | | `db.redis.database_index` | `15` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/database/sql.md b/docs/database/sql.md index f6cb792e23..7fe9370f79 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -39,4 +39,4 @@ This is an example of attributes for a MySQL database span: | `db.operation` | `"SELECT"` | | `db.sql.table` | `"orders"` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index 248f61d98b..e4bd767b8c 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -16,4 +16,4 @@ Semantic conventions for Exceptions are defined for the following signals: * [Exceptions on spans](exceptions-spans.md): Semantic Conventions for Exceptions associated with *spans*. * [Exceptions in logs](exceptions-logs.md): Semantic Conventions for Exceptions recorded in *logs*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index d9a8ef228d..32d20e68cf 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Experimental][DocumentStatus] This document defines semantic conventions for recording exceptions on -[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/event-api.md#emit-event) -emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/bridge-api.md#logger). +[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/event-api.md#emit-event) +emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#logger). @@ -21,7 +21,7 @@ emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry ## Recording an Exception Exceptions SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/bridge-api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#logger) emit operations. Exceptions MAY be recorded on "logs" or "events" depending on the context. @@ -33,7 +33,7 @@ the language runtime. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. | Attribute | Type | Description | Examples | Requirement Level | @@ -53,4 +53,4 @@ The table below indicates which attributes should be added to the Same as [Trace Semantic Conventions for Exceptions - Stacktrace Representation](exceptions-spans.md#stacktrace-representation). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index 46e73db77d..eef07f2cdb 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -23,7 +23,7 @@ An exception SHOULD be recorded as an `Event` on the span during which it occurr The name of the event MUST be `"exception"`. A typical template for an auto-instrumentation implementing this semantic convention -using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#record-exception) +using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#record-exception) could look like this (pseudo-Java): ```java @@ -109,4 +109,4 @@ grained information from a stacktrace, if necessary. [telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk [erlang-stacktrace]: https://www.erlang.org/doc/man/erl_error.html#format_exception-3 [elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/faas/README.md b/docs/faas/README.md index fce5377c6e..62ecf24d24 100644 --- a/docs/faas/README.md +++ b/docs/faas/README.md @@ -20,4 +20,4 @@ Technology specific semantic conventions are defined for the following FaaS serv * [AWS Lambda](aws-lambda.md): Semantic Conventions for *AWS Lambda*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 7aac91d1d2..56e0c07408 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -120,7 +120,7 @@ be ` process`. If there are multiple sources in the batch, the nam For every message in the event, the [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/context/api-propagators.md) and added as a link to the span. This means the span may have as many links as messages in the batch. See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. @@ -134,7 +134,7 @@ See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context- For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/context/api-propagators.md) and added as a link to the span. See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. @@ -261,4 +261,4 @@ because it is not available until function invocation. [environment variables]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 4ec721ded0..2505b5b5a3 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -82,4 +82,4 @@ FaaS providers. This list is not exhaustive. * [Google CloudFunctions Metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-cloudfunctions) * [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 31af78e346..2a06a3c1ec 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -261,4 +261,4 @@ This example shows the FaaS attributes for a (non-FaaS) process hosted on Google | Resource | `faas.instance` | n/a | `"my-lambda-function:instance-0001"` | | Resource | `cloud.resource_id` | n/a | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/feature-flags/README.md b/docs/feature-flags/README.md index e80a9de018..30a308837a 100644 --- a/docs/feature-flags/README.md +++ b/docs/feature-flags/README.md @@ -17,4 +17,4 @@ Semantic conventions for feature flags are defined for the following signals: * [Feature Flags in Spans](feature-flags-spans.md): Semantic Conventions for recording feature flags in *spans*. * [Feature Flags in Logs](feature-flags-logs.md): Semantic Conventions for recording feature flags in *logs*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 71eb813cf2..8f19707e75 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Experimental][DocumentStatus] This document defines semantic conventions for recording feature flag evaluations as -a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the -[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/bridge-api.md#emit-a-logrecord). +a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the +[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. To record a flag evaluation as a part of a transaction context, @@ -28,14 +28,14 @@ section of the trace semantic convention for feature flag evaluations. ## Recording an Evaluation Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/bridge-api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/bridge-api.md#logger) emit operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. The event name MUST be `feature_flag`. @@ -56,4 +56,4 @@ semantic identifier is unavailable. String representation of the value should be determined by the implementer. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md index 72bd3ef28f..0bf5de6174 100644 --- a/docs/feature-flags/feature-flags-spans.md +++ b/docs/feature-flags/feature-flags-spans.md @@ -60,4 +60,4 @@ semantic identifier is unavailable. String representation of the value should be determined by the implementer. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/events-general.md b/docs/general/events-general.md index 4991f586a4..a0441f393a 100644 --- a/docs/general/events-general.md +++ b/docs/general/events-general.md @@ -57,4 +57,4 @@ unrelated events. | `k8s` | Events from Kubernetes | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/general-attributes.md b/docs/general/general-attributes.md index 1c031cd057..aba52deb49 100644 --- a/docs/general/general-attributes.md +++ b/docs/general/general-attributes.md @@ -383,4 +383,4 @@ about the span. | `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/logs-general.md b/docs/general/logs-general.md index 22796ec2ef..3e93ec98f3 100644 --- a/docs/general/logs-general.md +++ b/docs/general/logs-general.md @@ -27,7 +27,7 @@ The following semantic conventions for logs are defined: * [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. Apart from semantic conventions for logs, [events](events-general.md), [traces](trace-general.md), and [metrics](metrics-general.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General log identification attributes @@ -47,7 +47,7 @@ The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID This section describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log. -**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`. +**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`. The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission. As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes. @@ -81,4 +81,4 @@ As such, these should be recorded as Log Record attributes when applicable. They | `stderr` | Events from stderr stream | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/metrics-general.md b/docs/general/metrics-general.md index 9c92afdaf4..a86eb69d96 100644 --- a/docs/general/metrics-general.md +++ b/docs/general/metrics-general.md @@ -35,7 +35,7 @@ The following semantic conventions surrounding metrics are defined: * [Runtime Environment](/docs/system/runtime-environment-metrics.md): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also -defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with +defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General Guidelines @@ -96,7 +96,7 @@ usable. When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the -[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/compatibility/prometheus_and_openmetrics.md). +[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/compatibility/prometheus_and_openmetrics.md). ### Pluralization @@ -223,4 +223,4 @@ For example, if you are tracking `active_requests` with an `UpDownCounter`, and request starts and decrementing it each time a request ends, then any attributes which are not yet available when incrementing the counter at request start should not be used when decrementing the counter at request end. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md index 677faf6b95..77ed44a13b 100644 --- a/docs/general/trace-compatibility.md +++ b/docs/general/trace-compatibility.md @@ -39,4 +39,4 @@ between a child Span and a parent Span, as defined by | `follows_from` | The parent Span does not depend in any way on the result of the child Span | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/trace-general.md b/docs/general/trace-general.md index 6a4d011715..f19b985c3d 100644 --- a/docs/general/trace-general.md +++ b/docs/general/trace-general.md @@ -33,5 +33,5 @@ The following semantic conventions for spans are defined: * [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). diff --git a/docs/http/README.md b/docs/http/README.md index 4b0b6c05e3..c12ecc2998 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -43,4 +43,4 @@ Semantic conventions for HTTP are defined for the following signals: * [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*. * [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 77b062b48b..3140041b7b 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -62,7 +62,7 @@ This metric is required. When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -373,7 +373,7 @@ This metric is required. When this metric is reported alongside an HTTP client span, the metric value SHOULD be the same as the HTTP client span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -577,4 +577,4 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index e333320895..1796f7f40a 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -59,7 +59,7 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name -HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#span). +HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a (low-cardinality) `http.route` available. HTTP server span names SHOULD be `{http.request.method}` if there is no (low-cardinality) @@ -73,7 +73,7 @@ default span name. ## Status -[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the +[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the 1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. @@ -511,4 +511,4 @@ GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) --- server (SERVER, trace=t2, span=s2) ``` -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/messaging/README.md b/docs/messaging/README.md index 46c2838bfd..e117836a2e 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -21,4 +21,4 @@ Technology specific semantic conventions are defined for the following messaging * [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*. * [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 979189fc91..fd494c4297 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -159,4 +159,4 @@ This section defines how to apply semantic conventions when collecting Kafka met | messaging.kafka.consumer.lag_sum | Gauge | Int64 | lag sum | `{lag sum}` | Current approximate sum of consumer group lag across all partitions of topic | `group` | The ID (string) of a consumer group | | | | | | | | `topic` | The ID (integer) of a topic | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index e85ea2ea23..2f7bf12adf 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -169,7 +169,7 @@ The span name SHOULD be set to the message destination name and the operation be ``` -The destination name SHOULD only be used for the span name if it is known to be of low cardinality (cf. [general span name guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#span)). +The destination name SHOULD only be used for the span name if it is known to be of low cardinality (cf. [general span name guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span)). This can be assumed if it is statically derived from application code or configuration. Wherever possible, the real destination names after resolving logical or aliased names SHOULD be used. If the destination name is dynamic, such as a [conversation ID](#conversations) or a value obtained from a `Reply-To` header, it SHOULD NOT be used for the span name. @@ -385,7 +385,7 @@ Process C: | Span Recv1 | Given is a process P, that publishes two messages to a queue Q on messaging system MS, and a process C, which receives them separately in two different operations (Span Recv1 and Recv2) and processes both messages in one batch (Span Proc1). -Since each span can only have one parent, C3 should not choose a random parent out of C1 and C2, but rather rely on the implicitly selected parent as defined by the [tracing API spec](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md). +Since each span can only have one parent, C3 should not choose a random parent out of C1 and C2, but rather rely on the implicitly selected parent as defined by the [tracing API spec](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md). Depending on the implementation, the producing spans might still be available in the meta data of the messages and should be added to C3 as links. The client library or application could also add the receiver span's SpanContext to the data structure it returns for each message. In this case, C3 could also add links to the receiver spans C1 and C2. @@ -423,4 +423,4 @@ More specific Semantic Conventions are defined for the following messaging techn * [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*. * [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 1f66215b16..3c5bff049c 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -23,4 +23,4 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 35d40d2231..a0b88daa06 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -52,4 +52,4 @@ Specific attributes for Apache RocketMQ are defined below. `messaging.client_id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/object-stores/README.md b/docs/object-stores/README.md index ec048f793b..3dd2eb6715 100644 --- a/docs/object-stores/README.md +++ b/docs/object-stores/README.md @@ -15,4 +15,4 @@ The following technology specific semantic conventions are defined for object st * [AWS S3](s3.md): Semantic Conventions for *AWS S3*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index f3ba8c4d0b..71d6c56360 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -68,4 +68,4 @@ The `part_number` attribute corresponds to the `--part-number` parameter of the [upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/README.md b/docs/resource/README.md index 82433c0997..0426bd6249 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -9,7 +9,7 @@ path_base_for_github_subdir: **Status**: [Mixed][DocumentStatus] -This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from +This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from [OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md). @@ -47,7 +47,7 @@ This document defines standard attributes for resources. These attributes are ty Attributes are grouped logically by the type of the concept that they described. Attributes in the same group have a common prefix that ends with a dot. For example all attributes that describe Kubernetes properties start with "k8s." -See [Attribute Requirement Levels](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-requirement-level.md) for details on when attributes +See [Attribute Requirement Levels](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md) for details on when attributes should be included. ## Attributes with Special Handling @@ -59,7 +59,7 @@ Given their significance some resource attributes are treated specifically as de ### Semantic Attributes with Dedicated Environment Variable These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/configuration/sdk-environment-variables.md): +as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/configuration/sdk-environment-variables.md): - [`service.name`](#service) - [`service.version`](#service) @@ -67,7 +67,7 @@ as specified in [OpenTelemetry Environment Variable Specification](https://githu ## Semantic Attributes with SDK-provided Default Value These are the attributes which MUST be provided by the SDK -as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/resource/sdk.md#sdk-provided-resource-attributes): +as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md#sdk-provided-resource-attributes): - [`service.name`](#service) - [`telemetry.sdk` group](#telemetry-sdk) @@ -233,4 +233,4 @@ Valid cloud providers are: - [Tencent Cloud](https://www.tencentcloud.com/) (`tencent_cloud`) - [Heroku dyno](./cloud-provider/heroku.md) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/browser.md b/docs/resource/browser.md index ef32ea4958..a914a1f24e 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -29,4 +29,4 @@ The list of possible values is defined in the [W3C User-Agent Client Hints speci **[5]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/README.md b/docs/resource/cloud-provider/README.md index e32de4b5b3..40e4d4822a 100644 --- a/docs/resource/cloud-provider/README.md +++ b/docs/resource/cloud-provider/README.md @@ -15,4 +15,4 @@ This document defines semantic conventions for resource cloud providers. * [GCP](gcp/README.md): Semantic Conventions for Google Cloud Platform. * [Heroku](heroku.md): Semantic Conventions for Heroku. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/README.md b/docs/resource/cloud-provider/aws/README.md index 936d808ddc..3e20b6848e 100644 --- a/docs/resource/cloud-provider/aws/README.md +++ b/docs/resource/cloud-provider/aws/README.md @@ -28,4 +28,4 @@ Attributes that relate to an individual AWS service: - [Elastic Container Service (ECS)](./ecs.md) - [Elastic Kubernetes Service (EKS)](./eks.md) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index 313ea19c16..ba3ae6183b 100644 --- a/docs/resource/cloud-provider/aws/ecs.md +++ b/docs/resource/cloud-provider/aws/ecs.md @@ -24,4 +24,4 @@ | `fargate` | fargate | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/eks.md b/docs/resource/cloud-provider/aws/eks.md index 99262aaa47..765108afce 100644 --- a/docs/resource/cloud-provider/aws/eks.md +++ b/docs/resource/cloud-provider/aws/eks.md @@ -12,4 +12,4 @@ | `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/aws/logs.md b/docs/resource/cloud-provider/aws/logs.md index b6e2139be3..d2238e68d6 100644 --- a/docs/resource/cloud-provider/aws/logs.md +++ b/docs/resource/cloud-provider/aws/logs.md @@ -21,4 +21,4 @@ **[3]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/gcp/README.md b/docs/resource/cloud-provider/gcp/README.md index ccaa39697a..6888ead5a1 100644 --- a/docs/resource/cloud-provider/gcp/README.md +++ b/docs/resource/cloud-provider/gcp/README.md @@ -19,4 +19,4 @@ provider (like account ID, operating system, etc), it belongs in the parent - [Cloud Run](./cloud-run.md) - [Compute Engine](./gce.md) -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/gcp/cloud-run.md b/docs/resource/cloud-provider/gcp/cloud-run.md index 75acf53528..ce884d3e1e 100644 --- a/docs/resource/cloud-provider/gcp/cloud-run.md +++ b/docs/resource/cloud-provider/gcp/cloud-run.md @@ -15,4 +15,4 @@ These conventions are recommended for resources running on Cloud Run. | `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud-provider/heroku.md b/docs/resource/cloud-provider/heroku.md index 4b11283db4..fb0171cd75 100644 --- a/docs/resource/cloud-provider/heroku.md +++ b/docs/resource/cloud-provider/heroku.md @@ -29,4 +29,4 @@ Additionally, [the `cloud.provider` resource attribute MUST be set to `heroku`]( [Heroku dyno metadata]: https://devcenter.heroku.com/articles/dyno-metadata -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index b9893a1e45..7967c30976 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -85,4 +85,4 @@ The following well-known definitions MUST be used if you set this attribute and | `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/container.md b/docs/resource/container.md index a4e169eef5..264a7d53bc 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -26,4 +26,4 @@ OCI defines a digest of manifest. **[2]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index 29a175b73a..847283447d 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -12,4 +12,4 @@ | `deployment.environment` | string | Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) (aka deployment tier). | `staging`; `production` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/device.md b/docs/resource/device.md index c3ba572242..174057e861 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -23,4 +23,4 @@ **[4]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/faas.md b/docs/resource/faas.md index b050716c6c..0ffacbfac9 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -80,4 +80,4 @@ There are cases where a FaaS resource attribute is better applied as a span attribute instead. See the [FaaS trace conventions](/docs/faas/faas-spans.md) for more. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/host.md b/docs/resource/host.md index 6dfd068695..96d7da4dea 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -57,4 +57,4 @@ detector implementations MUST not collect `host.id` from privileged sources. If privileged lookup of `host.id` is required, the value should be injected via the `OTEL_RESOURCE_ATTRIBUTES` environment variable. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index 3ac0faa3e9..6aada5e772 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -210,4 +210,4 @@ A CronJob creates Jobs on a repeating schedule. | `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/os.md b/docs/resource/os.md index 05780ace78..2b73acea08 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -33,4 +33,4 @@ In case of virtualized environments, this is the operating system as it is obser | `z_os` | IBM z/OS | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/process.md b/docs/resource/process.md index 9b0b4a7362..388f26129c 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -220,4 +220,4 @@ Examples for some Ruby runtimes | MRI | ruby | 2.7.1 | ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-darwin19] | | TruffleRuby | truffleruby | 2.6.2 | truffleruby (Shopify) 20.0.0-dev-92ed3059, like ruby 2.6.2, GraalVM CE Native [x86_64-darwin] | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/webengine.md b/docs/resource/webengine.md index c3f97d0085..8b3a0985c7 100644 --- a/docs/resource/webengine.md +++ b/docs/resource/webengine.md @@ -23,4 +23,4 @@ The situations where there are multiple candidates, it is up to instrumentation * Either Apache HTTP Server or `mod_wsgi` MAY be chosen as `webengine`, depending on the decision made by the instrumentation authors. * Django SHOULD NOT be set as an `webengine` as the required information is already available in instrumentation library and setting this into `webengine` would duplicate the information. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 5cc1fe593c..81105afb30 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -23,4 +23,4 @@ Technology specific semantic conventions are defined for the following RPC syste * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 2e98ceba54..f383bf7703 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -47,7 +47,7 @@ Below is a table of attributes that SHOULD be included on client and server Conn ## Connect RPC Status -If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. +If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. ## Connect RPC Request and Response Metadata @@ -59,4 +59,4 @@ If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-te **[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index bbcb2f9932..c5f140bf6f 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -47,10 +47,10 @@ Below is a table of attributes that SHOULD be included on client and server gRPC ## gRPC Status The table below describes when -the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#set-status) MUST be set +the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be set to `Error` or remain unset depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) -and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#spankind). +and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#spankind). | gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status | |---|---|---| @@ -82,4 +82,4 @@ and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tr **[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 82c5461f0b..3c26a8eeb9 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -26,4 +26,4 @@ described on this page. **[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 49e067bbba..f077245b6c 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -148,4 +148,4 @@ More specific Semantic Conventions are defined for the following RPC technologie * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 422c7768f8..9d600b1d58 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -204,4 +204,4 @@ More specific Semantic Conventions are defined for the following RPC technologie * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/README.md b/docs/system/README.md index 197a616730..7e6be0f0e4 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -18,4 +18,4 @@ System semantic conventions are defined for the following metrics: * [Process](process-metrics.md): For standard process metrics. * [Runtime Environment](runtime-environment-metrics.md): For runtime environment metrics. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 596fc56b6b..e5fb72cbfe 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -388,4 +388,4 @@ Additional **Recommended** attributes: | ----------------- | ---------------------- | ---------- | | `sensor_location` | Location of the sensor | `PS0 V3_3` | -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 93e1c5bf60..543ab85baa 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -48,4 +48,4 @@ Below is a table of Process metric instruments. Process metrics SHOULD be associated with a [`process`](/docs/resource/process.md#process) resource whose attributes provide additional context about the process. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index d28c355e90..e9411ed890 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -192,7 +192,7 @@ This metric is obtained by subscribing to [`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) of `[]` (single bucket histogram capturing count, sum, min, max). @@ -422,6 +422,6 @@ This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md -[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#opt-in -[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#recommended +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#opt-in +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 8aef8ad299..64e7e8f5c3 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -188,4 +188,4 @@ An instrument for load average over 1 minute on Linux could be named `system.linux.cpu.load_1m`, reusing the `cpu` name proposed above and having an `{os}` prefix to split this metric across OSes. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/url/README.md b/docs/url/README.md index ced1171890..af111395de 100644 --- a/docs/url/README.md +++ b/docs/url/README.md @@ -15,4 +15,4 @@ URL semantic conventions are defined for the following: * [URL](url.md): For describing URL and its components. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/url/url.md b/docs/url/url.md index c9f0cbbbaa..0661c8dd8f 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -48,4 +48,4 @@ Instrumentations that are aware of specific sensitive query string parameters MU _Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._ -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index 434b078228..761b9cee65 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -6,9 +6,9 @@ # Set this to the version number you want to CHANGE in URLs in the repository. -PREVIOUS_SPECIFICATION_VERSION="main" +PREVIOUS_SPECIFICATION_VERSION="v1.21.0" # Set this to the version number you want to KEEP in URLs in the repository. -LATEST_SPECIFICATION_VERSION="v1.21.0" +LATEST_SPECIFICATION_VERSION="v1.22.0" # The specific pattern we look for when replacing URLs SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/tree/" SPECIFICATION_BLOB_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/blob/" @@ -22,7 +22,7 @@ fix_file() { "$1" } -important_files=("specification" "model" "README.md" "supplementary-guidelines") +important_files=("docs" "model" "README.md" "supplementary-guidelines") # TODO - limit to markdown/yaml files? find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do diff --git a/model/README.md b/model/README.md index 6c0461484b..a6c52ba625 100644 --- a/model/README.md +++ b/model/README.md @@ -10,9 +10,9 @@ the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-naming.md), -[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-requirement-level.md), -and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/metric-requirement-level.md) conventions. +[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-naming.md), +[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md), +and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md) conventions. Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. From 5200be9d8da2cf5b169bea246e0291ee68e530a1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 13 Jul 2023 11:09:15 -0400 Subject: [PATCH 16/44] [CI] Report link-check error when external URL used for local doc page (#187) --- .markdown_link_check_config.json | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index dac3ae97bb..ea53f8a199 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -6,8 +6,12 @@ ], "replacementPatterns": [ { - "pattern": "^/", - "replacement": "{{BASEURL}}/" + "pattern": "^/", + "replacement": "{{BASEURL}}/" + }, + { + "pattern": "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/[^/]+/docs/", + "replacement": "LINK-CHECK-ERROR-USE-LOCAL-PATH-TO-DOC-PAGE-NOT-EXTERNAL-URL/" } ], "retryOn429": true, From 69f6baef5780f3586cde4ee2267100a99014cf16 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 13 Jul 2023 14:47:21 -0400 Subject: [PATCH 17/44] =?UTF-8?q?Update=20documentation=20for=20how=20to?= =?UTF-8?q?=20cut=20a=20release=20AND=20perform=20the=20action=20=E2=80=A6?= =?UTF-8?q?=20(#190)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 + CONTRIBUTING.md | 15 ++++ README.md | 6 -- internal/tools/schema_check.sh | 15 ++-- schema-next.yaml | 139 +++++++++++++++++++++++++++++++++ 5 files changed, 165 insertions(+), 12 deletions(-) create mode 100644 schema-next.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8cf30653..6580b21cdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ release. ## Unreleased +## v1.21.0 (2023-07-13) + Note: This is the first release of Semantic Conventions separate from the Specification. - Add GCP Bare Metal Solution as a cloud platform diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c73b5f458a..e69ec11749 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -122,3 +122,18 @@ make misspell-correction 3. Modify `LATEST_SPECIFICATION_VERSION` to the latest specification tag, e.g. `1.21` 4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`. 5. Add all modified files to the change submit and submit a PR. + +## Making a Release + +- Ensure the referenced specification version is up to date. Use + [tooling to update the spec](#updating-the-referenced-specification-version) + if needed. +- Create a staging branch for the release. + - Update `schema-next.yaml` file and move to `schemas/{version}` + - Ensure the `next` version is appropriately configured as the `{version}`. + - Copy `schema-next.yaml` to `schemas/{version}`. + - Add `next` as a version in `schema-next.yaml` version. + - Update `CHANGELOG.md` for the latest version. + - Add `## v{version} ({date})` under `## Unreleased` + - Send staging tag as PR for review. +- Create a tag `v{version}` on the merged PR and push remote. diff --git a/README.md b/README.md index e528b8d2d9..9967f6fb67 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,6 @@ This repository is currently using [this specification version][SpecificationVer The documentation currently resides in the [doc](docs/README.md) folder. -## TODOs - -- [ ] Set up SchemaURL publication -- [ ] Contributing.MD document -- [ ] Restructure markdown for easier consumption. - ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index ed88397e05..50c8d5e724 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -32,12 +32,15 @@ grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while re exit 3 fi - curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver - - diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \ - || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3) - - rm verify$ver + # Schema file will no be served directly from this repository when linked + # into opentelemetry.io. We disable this for now and need to move the check + # into the website. + # curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver + # + # diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \ + # || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3) + # + # rm verify$ver done # Now check the content of all schema files in the ../shemas directory. diff --git a/schema-next.yaml b/schema-next.yaml new file mode 100644 index 0000000000..37d35efc84 --- /dev/null +++ b/schema-next.yaml @@ -0,0 +1,139 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.21.0 +versions: + next: + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: From 12bd6b0999657362c17ff785c973a3fd1c7065c7 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 14 Jul 2023 08:10:49 -0400 Subject: [PATCH 18/44] [editorial] markdownlint in less then 1.5 sec (#193) --- .github/workflows/checks.yml | 2 +- CONTRIBUTING.md | 2 + Makefile | 5 +++ docs/general/general-attributes.md | 2 - docs/general/trace-general.md | 2 + docs/rpc/rpc-metrics.md | 2 - docs/rpc/rpc-spans.md | 1 - gulpfile.js | 60 ++++++++++++++++++++++++++++++ package.json | 10 ++++- 9 files changed, 79 insertions(+), 7 deletions(-) create mode 100644 gulpfile.js diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 9c94e529c7..4ae744dcbe 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -20,7 +20,7 @@ jobs: run: make check-file-and-folder-names-in-docs - name: run markdownlint - run: make markdownlint + run: npx gulp lint-md yamllint: runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69ec11749..158f74ee17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,3 +137,5 @@ make misspell-correction - Add `## v{version} ({date})` under `## Unreleased` - Send staging tag as PR for review. - Create a tag `v{version}` on the merged PR and push remote. + +[nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating diff --git a/Makefile b/Makefile index 1375040f7a..f62f8411f6 100644 --- a/Makefile +++ b/Makefile @@ -65,6 +65,11 @@ markdown-toc: .PHONY: markdownlint markdownlint: + @if ! npm ls markdownlint; then npm install; fi + @npx gulp lint-md + +.PHONY: markdownlint-old +markdownlint-old: @if ! npm ls markdownlint; then npm install; fi @for f in $(ALL_DOCS); do \ echo $$f; \ diff --git a/docs/general/general-attributes.md b/docs/general/general-attributes.md index aba52deb49..a8f0b0e79e 100644 --- a/docs/general/general-attributes.md +++ b/docs/general/general-attributes.md @@ -326,8 +326,6 @@ Examples of where the `enduser.id` value is extracted from: | [JavaEE/JakartaEE Servlet] | `javax.servlet.http.HttpServletRequest.getUserPrincipal()` | | [Windows Communication Foundation] | `ServiceSecurityContext.Current.PrimaryIdentity` | -[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 -[OAuth 2.0 Access Token]: https://tools.ietf.org/html/rfc6749#section-3.3 [SAML 2.0 Assertion]: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html [HTTP Basic/Digest Authentication]: https://tools.ietf.org/html/rfc2617 [OAuth 2.0 Bearer Token]: https://tools.ietf.org/html/rfc6750 diff --git a/docs/general/trace-general.md b/docs/general/trace-general.md index f19b985c3d..c2294a5978 100644 --- a/docs/general/trace-general.md +++ b/docs/general/trace-general.md @@ -35,3 +35,5 @@ The following semantic conventions for spans are defined: Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f077245b6c..829faf58da 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -131,8 +131,6 @@ To avoid high cardinality, implementations should prefer the most stable of `ser For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For server-side spans `server.port` is optional (it describes the port the client is connecting from). -[network.transport]: /docs/general/general-attributes.md#network-attributes - ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 9d600b1d58..aae3c5a0d7 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -131,7 +131,6 @@ This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. -[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes [`service.name`]: /docs/resource/README.md#service [`peer.service`]: /docs/general/general-attributes.md#general-remote-service-attributes diff --git a/gulpfile.js b/gulpfile.js new file mode 100644 index 0000000000..a42fd496e5 --- /dev/null +++ b/gulpfile.js @@ -0,0 +1,60 @@ +const gulp = require("gulp"); +const through2 = require("through2"); +const markdownlint = require("markdownlint"); +const yaml = require("js-yaml"); +const fs = require("fs"); + +let fileCount = 0, + issueCount = 0; + +function markdownLintFile(file, encoding, callback) { + const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); + const options = { + files: [file.path], + config: config, + }; + + markdownlint(options, function (err, result) { + if (err) { + console.error("ERROR occurred while running markdownlint: ", err); + return callback(err); + } + + const _resultString = (result || "").toString(); + // Result is a string with lines of the form: + // + // :\s*: + // + // Strip out any whitespace between the filepath and line number + // so that tools can jump directly to the line. + const resultString = _resultString + .split("\n") + .map((line) => line.replace(/^([^:]+):\s*(\d+):(.*)/, "$1:$2:$3")) + .join("\n"); + if (resultString) { + console.log(resultString); + issueCount++; + } + fileCount++; + callback(null, file); + }); +} + +function lintMarkdown() { + const markdownFiles = ["**/*.md", "!**/node_modules/**", "!**/.github/**"]; + + return gulp + .src(markdownFiles) + .pipe(through2.obj(markdownLintFile)) + .on("end", () => { + console.log( + `Processed ${fileCount} file${ + fileCount == 1 ? "" : "s" + }, ${issueCount} had issues.`, + ); + }); +} + +lintMarkdown.description = `Run markdownlint on all '*.md' files.`; + +gulp.task("lint-md", lintMarkdown); diff --git a/package.json b/package.json index 2cd780144d..0bbc27cb39 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,15 @@ { "devDependencies": { + "gulp": "^4.0.2", + "js-yaml": "^4.1.0", "markdown-link-check": "3.10.3", "markdown-toc": "^1.2.0", - "markdownlint-cli": "0.31.0" + "markdownlint": "^0.29.0", + "markdownlint-cli": "0.31.0", + "prettier": "^3.0.0", + "through2": "^4.0.2" + }, + "prettier": { + "proseWrap": "preserve" } } From b7e10e671dcc425321bae43e226f9d72cfd6020a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 14 Jul 2023 13:10:35 -0400 Subject: [PATCH 19/44] [editorial] Rename general section pages by dropping `general` from the filename (#195) --- Makefile | 2 +- docs/README.md | 8 +-- docs/database/database-metrics.md | 4 +- docs/database/database-spans.md | 16 ++--- docs/database/elasticsearch.md | 4 +- docs/faas/faas-metrics.md | 4 +- docs/general/README.md | 10 ++-- .../{general-attributes.md => attributes.md} | 1 + docs/general/{events-general.md => events.md} | 1 + docs/general/{logs-general.md => logs.md} | 3 +- .../{metrics-general.md => metrics.md} | 3 +- docs/general/{trace-general.md => trace.md} | 5 +- docs/http/http-metrics.md | 58 +++++++++---------- docs/http/http-spans.md | 42 +++++++------- docs/messaging/kafka.md | 8 +-- docs/messaging/messaging-spans.md | 20 +++---- docs/resource/faas.md | 2 +- docs/rpc/rpc-metrics.md | 20 +++---- docs/rpc/rpc-spans.md | 32 +++++----- docs/system/hardware-metrics.md | 34 +++++------ docs/system/process-metrics.md | 4 +- docs/system/runtime-environment-metrics.md | 16 +++-- docs/system/system-metrics.md | 16 ++--- model/resource/faas.yaml | 2 +- 24 files changed, 163 insertions(+), 152 deletions(-) rename docs/general/{general-attributes.md => attributes.md} (99%) rename docs/general/{events-general.md => events.md} (98%) rename docs/general/{logs-general.md => logs.md} (96%) rename docs/general/{metrics-general.md => metrics.md} (98%) rename docs/general/{trace-general.md => trace.md} (89%) diff --git a/Makefile b/Makefile index f62f8411f6..2e928e04f9 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.18.0 +SEMCONVGEN_VERSION=0.19.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/docs/README.md b/docs/README.md index 9cfd635f66..498f5e739c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,8 +35,8 @@ Semantic Conventions are defined for the following areas: Semantic Conventions by signals: -* [Events](general/events-general.md): Semantic Conventions for event data. -* [Logs](general/logs-general.md): Semantic Conventions for logs data. -* [Metrics](general/metrics-general.md): Semantic Conventions for metrics. +* [Events](general/events.md): Semantic Conventions for event data. +* [Logs](general/logs.md): Semantic Conventions for logs data. +* [Metrics](general/metrics.md): Semantic Conventions for metrics. * [Resource](resource/README.md): Semantic Conventions for resources. -* [Trace](general/trace-general.md): Semantic Conventions for traces and spans. +* [Trace](general/trace.md): Semantic Conventions for traces and spans. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 2946857bc3..7a24a76e98 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -29,7 +29,7 @@ and units. Below is a table of database client connection pool metric instruments that MUST be used by connection pool instrumentations: -| Name | Instrument | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | |-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| | `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. | @@ -43,7 +43,7 @@ Instrumentation libraries for database client connection pools that collect data following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments MUST NOT be used. -| Name | Instrument ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | |------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| | `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | | `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index cb60633ca0..9c60f6001e 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -65,19 +65,19 @@ Some database systems may allow a connection to switch to a different `db.user`, | `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. | -| [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | -| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | +| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | **[1]:** If using a port other than the default port for this DBMS and if `server.address` is set. **Additional attribute requirements:** At least one of the following sets of attributes is required: -* [`server.address`](../general/general-attributes.md) -* [`server.socket.address`](../general/general-attributes.md) +* [`server.address`](../general/attributes.md) +* [`server.socket.address`](../general/attributes.md) `db.system` 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. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index bf45239383..bf1aa46360 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -40,8 +40,8 @@ in order to map the path part values to their names. | [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required | | [`db.statement`](database-spans.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. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] | | `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below | -| [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | See below | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | | [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [4] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** 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. diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 2505b5b5a3..376ec3dc7d 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -36,7 +36,7 @@ type and units. Below is a table of FaaS invocation metric instruments. -| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | |------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| | `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | | `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | @@ -47,7 +47,7 @@ Below is a table of FaaS invocation metric instruments. Optionally, when applicable: -| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | +| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | |------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------| | `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | | `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of CPU usage per invocation | diff --git a/docs/general/README.md b/docs/general/README.md index 06f1511e40..ec1e248fda 100644 --- a/docs/general/README.md +++ b/docs/general/README.md @@ -12,11 +12,11 @@ This document defines general Semantic Conventions for spans, metrics, logs and The following general Semantic Conventions are defined: -* **[General attributes](general-attributes.md): General semantic attributes**. -* [Events](events-general.md): General Semantic Conventions for events. -* [Logs](logs-general.md): General Semantic Conventions for logs. -* [Metrics](metrics-general.md): General Semantic Conventions for metrics. -* [Spans](trace-general.md): General Semantic Conventions for traces / spans. +* **[General attributes](attributes.md): General semantic attributes**. +* [Events](events.md): General Semantic Conventions for events. +* [Logs](logs.md): General Semantic Conventions for logs. +* [Metrics](metrics.md): General Semantic Conventions for metrics. +* [Spans](trace.md): General Semantic Conventions for traces / spans. ## Event Name Reuse Prohibition diff --git a/docs/general/general-attributes.md b/docs/general/attributes.md similarity index 99% rename from docs/general/general-attributes.md rename to docs/general/attributes.md index a8f0b0e79e..13e98d5595 100644 --- a/docs/general/general-attributes.md +++ b/docs/general/attributes.md @@ -1,5 +1,6 @@ # General Attributes diff --git a/docs/general/events-general.md b/docs/general/events.md similarity index 98% rename from docs/general/events-general.md rename to docs/general/events.md index a0441f393a..bb05d9a015 100644 --- a/docs/general/events-general.md +++ b/docs/general/events.md @@ -1,5 +1,6 @@ # Semantic Conventions for Event Attributes diff --git a/docs/general/logs-general.md b/docs/general/logs.md similarity index 96% rename from docs/general/logs-general.md rename to docs/general/logs.md index 3e93ec98f3..0ccdbb7c73 100644 --- a/docs/general/logs-general.md +++ b/docs/general/logs.md @@ -1,5 +1,6 @@ # General Logs Attributes @@ -26,7 +27,7 @@ The following semantic conventions for logs are defined: * [Exceptions](/docs/exceptions/exceptions-logs.md): Semantic attributes that may be used in describing exceptions in logs. * [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. -Apart from semantic conventions for logs, [events](events-general.md), [traces](trace-general.md), and [metrics](metrics-general.md), +Apart from semantic conventions for logs, [events](events.md), [traces](trace.md), and [metrics](metrics.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). diff --git a/docs/general/metrics-general.md b/docs/general/metrics.md similarity index 98% rename from docs/general/metrics-general.md rename to docs/general/metrics.md index a86eb69d96..f4b03f34f6 100644 --- a/docs/general/metrics-general.md +++ b/docs/general/metrics.md @@ -1,5 +1,6 @@ # Metrics Semantic Conventions @@ -34,7 +35,7 @@ The following semantic conventions surrounding metrics are defined: * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/system/runtime-environment-metrics.md): For runtime environment metrics. -Apart from semantic conventions for metrics, [traces](trace-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also +Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). diff --git a/docs/general/trace-general.md b/docs/general/trace.md similarity index 89% rename from docs/general/trace-general.md rename to docs/general/trace.md index c2294a5978..af8e1c164e 100644 --- a/docs/general/trace-general.md +++ b/docs/general/trace.md @@ -1,5 +1,6 @@ # Trace Semantic Conventions @@ -19,7 +20,7 @@ can still be easily correlated and cross-analyzed. The following semantic conventions for spans are defined: -* **[General](general-attributes.md): General semantic attributes that may be used in describing different kinds of operations.** +* **[General](attributes.md): General semantic attributes that may be used in describing different kinds of operations.** * [Compatibility](trace-compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer. * [CloudEvents](/docs/cloudevents/README.md): Semantic Conventions for the CloudEvents spans. * [Cloud Providers](/docs/cloud-providers/README.md): Semantic Conventions for cloud providers spans. @@ -32,7 +33,7 @@ The following semantic conventions for spans are defined: * [Object Stores](/docs/object-stores/README.md): Semantic Conventions for object stores spans. * [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. -Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), +Apart from semantic conventions for traces, [metrics](metrics.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 3140041b7b..502d9e0a14 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -77,10 +77,10 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. @@ -153,8 +153,8 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | -| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. @@ -224,10 +224,10 @@ This metric is optional. | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. @@ -302,10 +302,10 @@ This metric is optional. | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** 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. @@ -387,11 +387,11 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | **[1]:** 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) @@ -456,11 +456,11 @@ This metric is optional. |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | **[1]:** 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) @@ -525,11 +525,11 @@ This metric is optional. |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | **[1]:** 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) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 1796f7f40a..946e1be2ca 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -100,10 +100,10 @@ sections below. | `http.request.body.size` | int | 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. | `3495` | Recommended | | `http.response.body.size` | int | 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. | `3495` | Recommended | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended | -| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | -| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | **[1]:** If and only if it's different than `http.request.method`. @@ -197,11 +197,11 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| [`server.address`](../general/general-attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`server.port`](../general/general-attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. | -| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. | +| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | | [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | **[1]:** 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). @@ -227,8 +227,8 @@ If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* [`server.address`](../general/general-attributes.md) -* [`server.port`](../general/general-attributes.md) +* [`server.address`](../general/attributes.md) +* [`server.port`](../general/attributes.md) * [`url.full`](../url/url.md) @@ -327,14 +327,14 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`client.address`](../general/general-attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | -| [`client.port`](../general/general-attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | -| [`client.socket.address`](../general/general-attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/general-attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`server.address`](../general/general-attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended | -| [`server.port`](../general/general-attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | -| [`server.socket.address`](../general/general-attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | -| [`server.socket.port`](../general/general-attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | +| [`client.address`](../general/attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | +| [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | +| [`client.socket.address`](../general/attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | +| [`client.socket.port`](../general/attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | +| [`server.socket.port`](../general/attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | | [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | | [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | @@ -371,8 +371,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* [`server.address`](../general/general-attributes.md) -* [`server.port`](../general/general-attributes.md) +* [`server.address`](../general/attributes.md) +* [`server.port`](../general/attributes.md) * [`url.path`](../url/url.md) * [`url.query`](../url/url.md) * [`url.scheme`](../url/url.md) diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index fd494c4297..47d36bb22f 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -42,7 +42,7 @@ For Apache Kafka, the following additional attributes are defined: **[2]:** If value is `true`. When missing, the value is assumed to be `false`. -For Apache Kafka producers, [`peer.service`](/docs/general/general-attributes.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to. +For Apache Kafka producers, [`peer.service`](/docs/general/attributes.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to. The `service.name` of a Consumer's Resource SHOULD match the `peer.service` of the Producer, when the message is directly passed to another service. If an intermediary broker is present, `service.name` and `peer.service` will not be the same. @@ -96,7 +96,7 @@ This section defines how to apply semantic conventions when collecting Kafka met **Description:** General Kafka metrics. -| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | +| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Attribute Key | Attribute Values | | ---------------------------------------------| ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | | messaging.kafka.messages | Counter | Int64 | messages | `{message}` | The number of messages received by the broker. | | | | messaging.kafka.requests.failed | Counter | Int64 | requests | `{request}` | The number of requests to the broker resulting in a failure. | `type` | `produce`, `fetch` | @@ -126,7 +126,7 @@ This section defines how to apply semantic conventions when collecting Kafka met **Description:** Kafka Producer level metrics. -| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | +| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Attribute Key | Attribute Values | | --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | | messaging.kafka.producer.outgoing-bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of outgoing bytes sent per second to all servers. | `client-id` | `client-id` value | | messaging.kafka.producer.responses.rate | Gauge | Double | responses per second | `{response}/s` | The average number of responses received per second. | `client-id` | `client-id` value | @@ -145,7 +145,7 @@ This section defines how to apply semantic conventions when collecting Kafka met **Description:** Kafka Consumer level metrics. -| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Attribute Key | Attribute Values | +| Name | Instrument | Value type | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Attribute Key | Attribute Values | | --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | | messaging.kafka.consumer.members | UpDownCounter | Int64 | members | `{member}` | Count of members in the consumer group | `group` | The ID (string) of a consumer group | | messaging.kafka.consumer.offset | Gauge | Int64 | offset | `{offset}` | Current offset of the consumer group at partition of topic | `group` | The ID (string) of a consumer group | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 2f7bf12adf..cee92e4815 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -221,14 +221,14 @@ The following operations related to messages are defined for these semantic conv | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [11] | | `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [12] | | `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [13] | -| [`network.protocol.name`](../general/general-attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended | -| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] | -| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] | +| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | **[1]:** If a custom value is used, it MUST be of low cardinality. @@ -292,8 +292,8 @@ Communication with broker is described with general [network attributes]. Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). -[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes -[`network.transport`]: /docs/general/general-attributes.md#network-attributes +[network attributes]: /docs/general/attributes.md#server-and-client-attributes +[`network.transport`]: /docs/general/attributes.md#network-attributes [Hangfire]: https://www.hangfire.io/ ### Consumer attributes diff --git a/docs/resource/faas.md b/docs/resource/faas.md index 0ffacbfac9..4de83ef8d7 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -25,7 +25,7 @@ See also: **[1]:** This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback function (which may be stored in the -[`code.namespace`/`code.function`](/docs/general/general-attributes.md#source-code-attributes) +[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) span attributes). For some cloud providers, the above definition is ambiguous. The following diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 829faf58da..aaa3647ad3 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,7 +61,7 @@ MUST be of the specified type and units. Below is a table of RPC server metric instruments. -| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Status | Streaming | +| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | |------|------------|------|-------------------------------------------|-------------|--------|-----------| | `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | | `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | @@ -74,7 +74,7 @@ Below is a table of RPC server metric instruments. Below is a table of RPC client metric instruments. These apply to traditional RPC usage, not streaming RPCs. -| Name | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics-general.md#instrument-units)) | Description | Status | Streaming | +| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | |------|------------|------|-------------------------------------------|-------------|--------|-----------| | `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | | `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | @@ -93,12 +93,12 @@ measurements. | [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | -| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: [4] | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | +| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: [4] | **[1]:** 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). @@ -110,8 +110,8 @@ measurements. **Additional attribute requirements:** At least one of the following sets of attributes is required: -* [`server.socket.address`](../general/general-attributes.md) -* [`server.address`](../general/general-attributes.md) +* [`server.socket.address`](../general/attributes.md) +* [`server.address`](../general/attributes.md) `rpc.system` 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. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index aae3c5a0d7..c86dfc3cac 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -86,12 +86,12 @@ Examples of span names: | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../general/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/general-attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | -| [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: [4] | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | See below | +| [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: [4] | **[1]:** 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). @@ -103,8 +103,8 @@ Examples of span names: **Additional attribute requirements:** At least one of the following sets of attributes is required: -* [`server.socket.address`](../general/general-attributes.md) -* [`server.address`](../general/general-attributes.md) +* [`server.socket.address`](../general/attributes.md) +* [`server.address`](../general/attributes.md) `rpc.system` 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. @@ -132,14 +132,14 @@ In this example, spans representing client request should have their `peer.servi Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. [`service.name`]: /docs/resource/README.md#service -[`peer.service`]: /docs/general/general-attributes.md#general-remote-service-attributes +[`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes ### Client attributes | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: [2] | +| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: [2] | **[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. @@ -151,12 +151,12 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`client.address`](../general/general-attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | -| [`client.port`](../general/general-attributes.md) | int | Client port number [2] | `65123` | Recommended | -| [`client.socket.address`](../general/general-attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/general-attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`client.address`](../general/attributes.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | +| [`client.port`](../general/attributes.md) | int | Client port number [2] | `65123` | Recommended | +| [`client.socket.address`](../general/attributes.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | +| [`client.socket.port`](../general/attributes.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | **[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available. diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index e5fb72cbfe..7c45d8bdcf 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -7,7 +7,7 @@ linkTitle: Hardware **Status**: [Experimental][DocumentStatus] This document describes instruments and attributes for common hardware level -metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions) +metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. @@ -52,7 +52,7 @@ Additionally, all metrics in `hw.` instruments have the following attributes: The below metrics apply to any type of hardware component. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ----------- | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | -------------------------- | | `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | | | `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `hw.error.type` (Recommended) | | @@ -75,7 +75,7 @@ monitored component: **Description:** Physical system as opposed to a virtual system or a container. Examples: physical server, switch or disk array. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ---------------- | | `hw.host.ambient_temperature` | Ambient (external) temperature of the physical host | Cel | Gauge | Double | | | | `hw.host.energy` | Total energy consumed by the entire physical host, in joules | J | Counter | Int64 | | | @@ -92,7 +92,7 @@ Examples: physical server, switch or disk array. **Description:** A battery in a computer system or an UPS. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------- | ----------------------------------------------------- | | `hw.battery.charge` | Remaining fraction of battery charge | 1 | Gauge | Double | | | | `hw.battery.charge.limit` | Lower limit of battery charge fraction to ensure proper operation | 1 | Gauge | Double | `limit_type` (Recommended) | `critical`, `throttled`, `degraded` | @@ -116,7 +116,7 @@ describe the characteristics of the monitored battery: the operating system for multi-core systems). A physical processor may include many individual cores. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- | | `hw.errors` | Total number of errors encountered and corrected by the CPU | {error} | Counter | Int64 | `hw.type` (**Required**) | `cpu` | | `hw.cpu.speed` | CPU current frequency | Hz | Gauge | Int64 | | | @@ -136,7 +136,7 @@ Additional **Recommended** attributes: **Description:** Controller that controls the physical disks and organize them in RAID sets and logical disks that are exposed to the operating system. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | | `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | | | | | | | `hw.type` (**Required**) | `disk_controller` | @@ -156,7 +156,7 @@ Additional **Recommended** attributes: **Description:** Computer chassis (can be an expansion enclosure) -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | ---------------------------------- | | `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `open` | | | | | | | `hw.type` (**Required**) | `enclosure` | @@ -176,7 +176,7 @@ Additional **Recommended** attributes: **Description:** Fan that keeps the air flowing to maintain the internal temperature of a computer -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------------ | ------------------------------------- | | `hw.fan.speed` | Fan speed in revolutions per minute | rpm | Gauge | Int | | | | `hw.fan.speed.limit` | Speed limit in rpm | rpm | Gauge | Int | `limit_type` (**Recommended**) | `low.critical`, `low.degraded`, `max` | @@ -194,7 +194,7 @@ Additional **Recommended** attributes: **Description:** Graphics Processing Unit (discrete) -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | ----------------------------------------------- | | `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `corrected`, `uncorrected` | | | | | | | `hw.type` (**Required**) | `gpu` | @@ -223,7 +223,7 @@ Additional **Recommended** attributes: controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed as /dev/hdd0 by the controller). -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | | `hw.errors` | Number of errors encountered on this logical disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `logical_disk` | | `hw.logical_disk.limit` | Size of the logical disk | By | UpDownCounter | Int64 | | | @@ -242,7 +242,7 @@ Additional **Recommended** attributes: **Description:** A memory module in a computer system. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------- | | `hw.errors` | Number of errors encountered on this memory module | {error} | Counter | Int64 | `hw.type` (**Required**) | `memory` | | `hw.memory.size` | Size of the memory module | By | UpDownCounter | Int64 | | | @@ -265,7 +265,7 @@ Additional **Recommended** attributes: physical network interface on a server, switch, router or firewall, an HBA, a fiber channel port or a Wi-Fi adapter. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | ----------------------------- | --------------------------------- | | `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. | | | | | | | `hw.type` (**Required**) | `network` | @@ -292,7 +292,7 @@ Additional **Recommended** attributes: **Description:** Physical hard drive (HDD or SDD) -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- | | `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `bad_sector`, `write`, etc. | | | | | | | `hw.type` (**Required**) | `physical_disk` | @@ -317,7 +317,7 @@ Additional **Recommended** attributes: **Description:** Power supply converting AC current to DC used by the motherboard and the GPUs -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ------------------------------ | | `hw.power_supply.limit` | Maximum power output of the power supply | W | UpDownCounter | Int64 | `limit_type` (Recommended) | `max`, `critical`, `throttled` | | `hw.power_supply.utilization` | Utilization of the power supply as a fraction of its maximum output | 1 | Gauge | Double | | | @@ -337,7 +337,7 @@ Additional **Recommended** attributes: **Description:** A tape drive in a computer or in a tape library (excluding virtual tape libraries) -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- | | `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.error.type` | `read`, `write`, `mount`, etc. | | | | | | | `hw.type` (**Required**) | `tape_drive` | @@ -357,7 +357,7 @@ Additional **Recommended** attributes: **Description:** A temperature sensor, either numeric or discrete -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ---------------------- | --------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | | `hw.temperature` | Temperature in degrees Celsius | Cel | Gauge | Double | | | | `hw.temperature.limit` | Temperature limit in degrees Celsius | Cel | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | @@ -374,7 +374,7 @@ Additional **Recommended** attributes: **Description:** A voltage sensor, either numeric or discrete -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | -------------------- | ----------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | | `hw.voltage.limit` | Voltage limit in Volts | V | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | | `hw.voltage.nominal` | Nominal (expected) voltage | V | Gauge | Double | | | diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 543ab85baa..d287b94a7d 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -8,7 +8,7 @@ linkTitle: Process This document describes instruments and attributes for common OS process level metrics in OpenTelemetry. Also consider the [general metric semantic -conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions) when creating +conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in this document. OS process metrics are not related to the runtime environment of the program, and should take measurements from the operating system. For runtime environment metrics see @@ -31,7 +31,7 @@ metrics](runtime-environment-metrics.md). Below is a table of Process metric instruments. -| Name | Instrument Type ([\*](/docs/general/metrics-general.md#instrument-types)) | Unit | Description | Labels | +| Name | Instrument Type ([\*](/docs/general/metrics.md#instrument-types)) | Unit | Description | Labels | |---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | | `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index e9411ed890..b51e8dd717 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -8,7 +8,7 @@ linkTitle: Runtime Environment This document includes semantic conventions for runtime environment level metrics in OpenTelemetry. Also consider the [general -metric](/docs/general/metrics-general.md#general-metric-semantic-conventions), [system +metric](/docs/general/metrics.md#general-metric-semantic-conventions), [system metrics](system-metrics.md) and [OS Process metrics](process-metrics.md) semantic conventions when instrumenting runtime environments. @@ -56,7 +56,7 @@ discussion. Metrics specific to a certain runtime environment should be prefixed with `process.runtime.{environment}.` and follow the semantic conventions outlined in [general metric semantic -conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions). Authors of +conventions](/docs/general/metrics.md#general-metric-semantic-conventions). Authors of runtime instrumentations are responsible for the choice of `{environment}` to avoid ambiguity when interpreting a metric's name or values. @@ -299,7 +299,9 @@ Note that the JVM does not provide a definition of what "recent" means. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. | +| `process.runtime.jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). @@ -345,7 +347,9 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https:/ | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. | +| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | + +**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). @@ -359,7 +363,9 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `1` | Average CPU load of the whole system for the last minute as reported by the JVM. | +| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `1` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | + +**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 64e7e8f5c3..3882a55788 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -8,7 +8,7 @@ linkTitle: System This document describes instruments and attributes for common system level metrics in OpenTelemetry. Consider the [general metric semantic -conventions](/docs/general/metrics-general.md#general-metric-semantic-conventions) when creating +conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. @@ -33,7 +33,7 @@ instruments not explicitly defined in the specification. **Description:** System level processor metrics. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | | ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | | system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. | | | | | | | cpu | CPU number [0..n-1] | @@ -45,7 +45,7 @@ instruments not explicitly defined in the specification. **Description:** System level memory metrics. This does not include [paging/swap memory](#systempaging---pagingswap-metrics). -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | ------------------------ | | system.memory.usage | | By | UpDownCounter | Int64 | state | used, free, cached, etc. | | system.memory.utilization | | 1 | Gauge | Double | state | used, free, cached, etc. | @@ -54,7 +54,7 @@ memory](#systempaging---pagingswap-metrics). **Description:** System level paging/swap memory metrics. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | |---------------------------|-------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| | system.paging.usage | Unix swap or windows pagefile usage | By | UpDownCounter | Int64 | state | used, free | | system.paging.utilization | | 1 | Gauge | Double | state | used, free | @@ -66,7 +66,7 @@ memory](#systempaging---pagingswap-metrics). **Description:** System level disk performance metrics. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | |--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| | system.disk.io | | By | Counter | Int64 | device | (identifier) | | | | | | | direction | read, write | @@ -101,7 +101,7 @@ perf counter (similar for Writes) **Description:** System level filesystem metrics. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ----------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | -------------------- | | system.filesystem.usage | | By | UpDownCounter | Int64 | device | (identifier) | | | | | | | state | used, free, reserved | @@ -118,7 +118,7 @@ perf counter (similar for Writes) **Description:** System level network metrics. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | |----------------------------------------|-------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packet} | Counter | Int64 | device | (identifier) | | | | | | | direction | transmit, receive | @@ -155,7 +155,7 @@ from **Description:** System level aggregate process metrics. For metrics at the individual process level, see [process metrics](process-metrics.md). -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics-general.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | | ------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | | system.processes.count | Total number of processes in each state | {process} | UpDownCounter | Int64 | status | running, sleeping, [etc.](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | | system.processes.created | Total number of processes created over uptime of the host | {process} | Counter | Int64 | - | - | diff --git a/model/resource/faas.yaml b/model/resource/faas.yaml index cf226889ac..7f1a02e0e0 100644 --- a/model/resource/faas.yaml +++ b/model/resource/faas.yaml @@ -14,7 +14,7 @@ groups: This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback function (which may be stored in the - [`code.namespace`/`code.function`](/docs/general/general-attributes.md#source-code-attributes) + [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) span attributes). For some cloud providers, the above definition is ambiguous. The following From 89e160384f1bd14d41c969aac4e6c15f2fd54bea Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 21 Jul 2023 10:34:45 -0400 Subject: [PATCH 20/44] [editorial] Setup Prettier and run it on some files (#192) Co-authored-by: Armin Ruech --- .markdown_link_check_config.json | 5 +-- .prettierignore | 8 ++++ CHANGELOG.md | 28 ++++++------ CONTRIBUTING.md | 7 +-- Makefile | 12 +++++- README.md | 4 +- docs/cloud-providers/README.md | 2 +- docs/cloud-providers/aws-sdk.md | 6 ++- docs/cloudevents/README.md | 2 +- docs/cloudevents/cloudevents-spans.md | 43 ++++++++++--------- package.json | 9 ++++ supplementary-guidelines/compatibility/aws.md | 4 +- 12 files changed, 79 insertions(+), 51 deletions(-) create mode 100644 .prettierignore diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index ea53f8a199..368aba40aa 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -15,8 +15,5 @@ } ], "retryOn429": true, - "aliveStatusCodes": [ - 200, - 403 - ] + "aliveStatusCodes": [200, 403] } diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000000..aa4edb3751 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,8 @@ +/.github + +# for the first iteration, we only reformat /docs/cloud* and will add the rest in individual PRs +/docs/** +!/docs/cloud* +!/docs/cloud*/** +/model +/schemas diff --git a/CHANGELOG.md b/CHANGELOG.md index 6580b21cdf..a3eeafab76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,9 +12,9 @@ release. Note: This is the first release of Semantic Conventions separate from the Specification. - Add GCP Bare Metal Solution as a cloud platform - ([#64](https://github.com/open-telemetry/semantic-conventions/pull/64)) + ([#64](https://github.com/open-telemetry/semantic-conventions/pull/64)) - Clarify the scope of the HTTP client span. - ([#3290](https://github.com/open-telemetry/opentelemetry-specification/pull/3290)) + ([#3290](https://github.com/open-telemetry/opentelemetry-specification/pull/3290)) - Add moratorium on relying on schema transformations for telemetry stability ([#3380](https://github.com/open-telemetry/opentelemetry-specification/pull/3380)) - Mark "Instrumentation Units" and "Instrumentation Types" sections of the general @@ -34,15 +34,15 @@ Note: This is the first release of Semantic Conventions separate from the Specif ([#3443](https://github.com/open-telemetry/opentelemetry-specification/pull/3443)) - Rename `net.peer.*`, `net.host.*`, and `net.sock.*` attributes to align with ECS ([#3402](https://github.com/open-telemetry/opentelemetry-specification/pull/3402)) - BREAKING: rename `net.peer.name` to `server.address` on client side and to `client.address` on server side, - `net.peer.port` to `server.port` on client side and to `client.port` on server side, - `net.host.name` and `net.host.port` to `server.address` and `server.port` (since `net.host.*` attributes only applied to server instrumentation), - `net.sock.peer.addr` to `server.socket.address` on client side and to `client.socket.address` on server side, - `net.sock.peer.port` to `server.socket.port` on client side and to `client.socket.port` on server side, - `net.sock.peer.name` to `server.socket.domain` (since `net.sock.peer.name` only applied to client instrumentation), - `net.sock.host.addr` to `server.socket.address` (since `net.sock.host.*` only applied to server instrumentation), - `net.sock.host.port` to `server.socket.port` (similarly since `net.sock.host.*` only applied to server instrumentation), - `http.client_ip` to `client.address` + BREAKING: rename `net.peer.name` to `server.address` on client side and to `client.address` on server side, + `net.peer.port` to `server.port` on client side and to `client.port` on server side, + `net.host.name` and `net.host.port` to `server.address` and `server.port` (since `net.host.*` attributes only applied to server instrumentation), + `net.sock.peer.addr` to `server.socket.address` on client side and to `client.socket.address` on server side, + `net.sock.peer.port` to `server.socket.port` on client side and to `client.socket.port` on server side, + `net.sock.peer.name` to `server.socket.domain` (since `net.sock.peer.name` only applied to client instrumentation), + `net.sock.host.addr` to `server.socket.address` (since `net.sock.host.*` only applied to server instrumentation), + `net.sock.host.port` to `server.socket.port` (similarly since `net.sock.host.*` only applied to server instrumentation), + `http.client_ip` to `client.address` - BREAKING: Introduce `network.transport` defined as [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). @@ -349,7 +349,7 @@ This and earlier versions were released as part of [the Specification](https://g ([#2508](https://github.com/open-telemetry/opentelemetry-specification/pull/2508)). - Refactor jvm classes semantic conventions ([#2550](https://github.com/open-telemetry/opentelemetry-specification/pull/2550)). -- Add browser.* attributes +- Add browser.\* attributes ([#2353](https://github.com/open-telemetry/opentelemetry-specification/pull/2353)). - Change JVM runtime metric `process.runtime.jvm.memory.max` to `process.runtime.jvm.memory.limit` @@ -487,13 +487,13 @@ This and earlier versions were released as part of [the Specification](https://g - Add `arch` to `host` semantic conventions ([#1483](https://github.com/open-telemetry/opentelemetry-specification/pull/1483)) - Add `runtime` to `container` semantic conventions ([#1482](https://github.com/open-telemetry/opentelemetry-specification/pull/1482)) - Rename `gcp_gke` to `gcp_kubernetes_engine` to have consistency with other -Google products under `cloud.infrastructure_service` ([#1496](https://github.com/open-telemetry/opentelemetry-specification/pull/1496)) + Google products under `cloud.infrastructure_service` ([#1496](https://github.com/open-telemetry/opentelemetry-specification/pull/1496)) - `http.url` MUST NOT contain credentials ([#1502](https://github.com/open-telemetry/opentelemetry-specification/pull/1502)) - Add `aws.eks.cluster.arn` to EKS specific semantic conventions ([#1484](https://github.com/open-telemetry/opentelemetry-specification/pull/1484)) - Rename `zone` to `availability_zone` in `cloud` semantic conventions ([#1495](https://github.com/open-telemetry/opentelemetry-specification/pull/1495)) - Rename `cloud.infrastructure_service` to `cloud.platform` ([#1530](https://github.com/open-telemetry/opentelemetry-specification/pull/1530)) - Add section describing that libraries and the collector should autogenerate -the semantic convention keys. ([#1515](https://github.com/open-telemetry/opentelemetry-specification/pull/1515)) + the semantic convention keys. ([#1515](https://github.com/open-telemetry/opentelemetry-specification/pull/1515)) ## v1.0.1 (2021-02-11) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 158f74ee17..bc249e0823 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,7 @@ The Specification has a number of tools it uses to check things like style, spelling and link validity. Before using the tools: - Install the latest LTS release of **[Node](https://nodejs.org/)**. -For example, using **[nvm][]** under Linux run: + For example, using **[nvm][]** under Linux run: ```bash nvm install --lts @@ -41,7 +41,7 @@ make check ``` Note: This can take a long time as it checks all links. You should use this -prior to submitting a PR to ensure validity. However, you can run individual +prior to submitting a PR to ensure validity. However, you can run individual checks directly. See: @@ -49,6 +49,7 @@ See: - [MarkdownStyle](#markdown-style) - [Misspell Check](#misspell-check) - Markdown link checking (docs TODO) +- Prettier formatting ### YAML to Markdown @@ -125,7 +126,7 @@ make misspell-correction ## Making a Release -- Ensure the referenced specification version is up to date. Use +- Ensure the referenced specification version is up to date. Use [tooling to update the spec](#updating-the-referenced-specification-version) if needed. - Create a staging branch for the release. diff --git a/Makefile b/Makefile index 2e928e04f9..4d04b73d8f 100644 --- a/Makefile +++ b/Makefile @@ -102,14 +102,22 @@ table-check: schema-check: $(TOOLS_DIR)/schema_check.sh +.PHONY: check-format +check-format: + npm run check:format + +.PHONY: fix-format +fix-format: + npm run fix:format + # Run all checks in order of speed / likely failure. .PHONY: check -check: misspell markdownlint markdown-link-check +check: misspell markdownlint markdown-link-check check-format @echo "All checks complete" # Attempt to fix issues / regenerate tables. .PHONY: fix -fix: table-generation misspell-correction +fix: table-generation misspell-correction fix-format @echo "All autofixes complete" .PHONY: install-tools diff --git a/README.md b/README.md index 9967f6fb67..d568e1955d 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian - [Ted Young](https://github.com/tedsuo), Lightstep -*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).* +_Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)._ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers)): @@ -33,6 +33,6 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs - [Armin Ruech](https://github.com/arminru) - [Reiley Yang](https://github.com/reyang) -*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).* +_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._ [SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0 diff --git a/docs/cloud-providers/README.md b/docs/cloud-providers/README.md index c50f4993c3..d9d43accec 100644 --- a/docs/cloud-providers/README.md +++ b/docs/cloud-providers/README.md @@ -13,6 +13,6 @@ This document defines semantic conventions for cloud provider SDK spans, metrics Semantic conventions exist for the following cloud provider SDKs: -* [AWS SDK](aws-sdk.md): Semantic Conventions for the *AWS SDK*. +- [AWS SDK](aws-sdk.md): Semantic Conventions for the _AWS SDK_. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 27856a3ac4..2c4d0ae012 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -23,6 +23,7 @@ The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, `S3.ListBuckets`. This is equivalent to concatenating `rpc.service` and `rpc.method` with `.` and consistent with the naming guidelines for RPC client spans. + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| @@ -35,12 +36,13 @@ with the naming guidelines for RPC client spans. **[2]:** 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). + ## AWS service specific attributes The following Semantic Conventions extend the general AWS SDK attributes for specific AWS services: -* [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*. -* [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for *AWS S3*. +- [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for _AWS DynamoDB_. +- [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for _AWS S3_. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/cloudevents/README.md b/docs/cloudevents/README.md index 4ba6cde6bb..b6d66070c9 100644 --- a/docs/cloudevents/README.md +++ b/docs/cloudevents/README.md @@ -13,6 +13,6 @@ This document defines semantic conventions for the [CloudEvents specification](h Semantic conventions for CloudEvents are defined for the following signals: -* [CloudEvents Spans](cloudevents-spans.md): Semantic Conventions for modeling CloudEvents as *spans*. +- [CloudEvents Spans](cloudevents-spans.md): Semantic Conventions for modeling CloudEvents as _spans_. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index d2e94c847a..d13a8d5300 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -6,7 +6,7 @@ linkTitle: CloudEvents Spans **Status**: [Experimental][DocumentStatus] - + @@ -20,14 +20,15 @@ linkTitle: CloudEvents Spans + + ## Definitions - From the - [CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview): +From the +[CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview): > CloudEvents is a specification for describing event data in common formats -to provide interoperability across services, platforms and systems. -> +> to provide interoperability across services, platforms and systems. For more information on the concepts, terminology and background of CloudEvents consult the @@ -39,7 +40,7 @@ document. A CloudEvent can be sent directly from producer to consumer. For such a scenario, the traditional parent-child trace model works well. However, CloudEvents are also used in distributed systems where an event -can go through many [hops](https://en.wikipedia.org/wiki/Hop_(networking)) +can go through many [hops]() until it reaches a consumer. In this scenario, the traditional parent-child trace model is not sufficient to produce a meaningful trace. @@ -49,13 +50,13 @@ Consider the following scenario: +----------+ +--------------+ | Producer | ---------------> | Intermediary | +----------+ +--------------+ - | - | - | - v -+----------+ +----------+ -| Consumer | <----------------- | Queue | -+----------+ +----------+ + | + | + | + v ++----------+ +----------+ +| Consumer | <----------------- | Queue | ++----------+ +----------+ ``` With the traditional parent-child trace model, the above scenario would produce @@ -159,12 +160,12 @@ Instrumentation SHOULD create a new span and populate the on the event. This applies when: - A CloudEvent is created by the instrumented library. -It may be impossible or impractical to create the Span during event -creation (e.g. inside the constructor or in a factory method), -so instrumentation MAY create the Span later, when passing the event to the transport layer. + It may be impossible or impractical to create the Span during event + creation (e.g. inside the constructor or in a factory method), + so instrumentation MAY create the Span later, when passing the event to the transport layer. - A CloudEvent is created outside of the instrumented library -(e.g. directly constructed by the application owner, without calling a constructor or factory method), -and passed without the Distributed Tracing Extension populated. + (e.g. directly constructed by the application owner, without calling a constructor or factory method), + and passed without the Distributed Tracing Extension populated. In case a CloudEvent is passed to the instrumented library with the Distributed Tracing Extension already populated, instrumentation MUST NOT create @@ -175,7 +176,7 @@ a span and MUST NOT modify the Distributed Tracing Extension on the event. - Span kind: PRODUCER - Span attributes: Instrumentation MUST add the required attributes defined -in the [table below](#attributes). + in the [table below](#attributes). #### Processing @@ -191,12 +192,13 @@ Instrumentation MAY add attributes to the link to further describe it. - Span kind: CONSUMER - Span attributes: Instrumentation MUST add the required attributes defined -in the [table below](#attributes). + in the [table below](#attributes). ### Attributes The following attributes are applicable to creation and processing Spans. + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| @@ -206,5 +208,6 @@ The following attributes are applicable to creation and processing Spans. | `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended | | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended | + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/package.json b/package.json index 0bbc27cb39..d51304272a 100644 --- a/package.json +++ b/package.json @@ -1,4 +1,13 @@ { + "scripts": { + "_check:format": "npx prettier --check .", + "_check:format:any": "npx prettier --check --ignore-path ''", + "check": "make check", + "check:format": "npm run _check:format || (echo '[help] Run: npm run format'; exit 1)", + "fix": "make fix", + "fix:format": "npm run _check:format -- --write", + "test": "npm run check" + }, "devDependencies": { "gulp": "^4.0.2", "js-yaml": "^4.1.0", diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index db8086066f..3777cb22a9 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -29,11 +29,11 @@ Propagation headers must be added before the signature is calculated to prevent errors on signed requests. If injecting into the request itself (not just adding additional HTTP headers), additional considerations may apply (for example, the .NET AWS SDK calculates a hash of the attributes it sends and compares it with -the `MD5OfMessageAttributes` that it receives). +the `MD5OfMessageAttributes` that it receives). The following formats are currently natively supported by AWS services for propagation: -* [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) +- [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) AWS service-supported context propagation is necessary to allow context propagation through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`. From c31e03cc8fc9226c001b7529b7aea9cd46386909 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 07:39:39 -0700 Subject: [PATCH 21/44] Editorial: Remove overlooked messaging.source attributes from aws lambda examples (#200) Co-authored-by: Armin Ruech --- docs/faas/aws-lambda.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 56e0c07408..4a673a6cbe 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -127,7 +127,6 @@ See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context- - [`faas.trigger`][faas] MUST be set to `pubsub`. - [`messaging.operation`](/docs/messaging/messaging-spans.md) MUST be set to `process`. - [`messaging.system`](/docs/messaging/messaging-spans.md) MUST be set to `AmazonSQS`. -- [`messaging.destination.kind` or `messaging.source.kind`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `queue`. ### SQS Message @@ -220,15 +219,12 @@ Function F: | Span ProcBatch | | SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | | Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | | `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | -| `messaging.destination.name` | `Q` | `Q` | | | | -| `messaging.source.name` | | | `Q` | `Q` | `Q` | -| `messaging.destination.kind` | `queue` | `queue` | | | | -| `messaging.source.kind` | | | `queue` | `queue` | `queue` | +| `messaging.destination.name` | `Q` | `Q` | `Q` | `Q` | `Q` | | `messaging.operation` | | | `process` | `process` | `process` | | `messaging.message.id` | | | | `"a1"` | `"a2"` | Note that if Span Prod1 and Span Prod2 were sent to different queues, Span ProcBatch would not have -`messaging.source.name` set as it would correspond to multiple sources. +`messaging.destination.name` set as it would correspond to multiple queues. The above requires user code change to create `Span Proc1` and `Span Proc2`. In Java, the user would inherit from [TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise these two spans From de2cf452747baa77ea6b40110e1f35b87697fcce Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 21 Jul 2023 16:54:19 +0200 Subject: [PATCH 22/44] Fix the unit of metric.process.runtime.jvm.system.cpu.load_1m to be {run_queue_item} (#95) Co-authored-by: Armin Ruech --- CHANGELOG.md | 3 +++ docs/system/runtime-environment-metrics.md | 2 +- model/metrics/process-runtime-jvm-metrics-experimental.yaml | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3eeafab76..800a0d08a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ release. ## Unreleased +- Fix the unit of metric.process.runtime.jvm.system.cpu.load_1m to be {run_queue_item} + ([#95](https://github.com/open-telemetry/semantic-conventions/pull/95)) + ## v1.21.0 (2023-07-13) Note: This is the first release of Semantic Conventions separate from the Specification. diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index b51e8dd717..280450102c 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -363,7 +363,7 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `1` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | +| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | **[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). diff --git a/model/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/process-runtime-jvm-metrics-experimental.yaml index 6b5d5b60d4..3956368631 100644 --- a/model/metrics/process-runtime-jvm-metrics-experimental.yaml +++ b/model/metrics/process-runtime-jvm-metrics-experimental.yaml @@ -29,7 +29,7 @@ groups: (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). instrument: gauge - unit: "1" + unit: "{run_queue_item}" - id: attributes.process.runtime.jvm.buffer type: attribute_group From be826421e85f260a7a322d1fe9c87040336c0f41 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 25 Jul 2023 13:47:37 +0200 Subject: [PATCH 23/44] Change company affiliation for Johannes (#207) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d568e1955d..28ddc8967e 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope - [Christian Neumüller](https://github.com/Oberon00), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian - [Joao Grassi](https://github.com/joaopgrassi), Dynatrace -- [Johannes Tax](https://github.com/pyohannes), Microsoft +- [Johannes Tax](https://github.com/pyohannes), Grafana Labs - [Liudmila Molkova](https://github.com/lmolkova), Microsoft - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian - [Ted Young](https://github.com/tedsuo), Lightstep From fe818fdec186d813aa7a75a5b9c07bad562759bd Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 25 Jul 2023 11:00:55 -0700 Subject: [PATCH 24/44] `.count` metric naming convention only applies to UpDownCounters (#107) --- CHANGELOG.md | 3 +++ docs/general/metrics.md | 20 ++++++++++++++++---- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 800a0d08a3..e60ef60c1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. - Fix the unit of metric.process.runtime.jvm.system.cpu.load_1m to be {run_queue_item} ([#95](https://github.com/open-telemetry/semantic-conventions/pull/95)) +- Update `.count` metric naming convention so that it only applies to UpDownCounters, + and add that `.total` should not be used by either Counters or UpDownCounters + ([#107](https://github.com/open-telemetry/opentelemetry-specification/pull/107)) ## v1.21.0 (2023-07-13) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index f4b03f34f6..3ba128a273 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -12,8 +12,10 @@ aliases: [docs/specs/semconv/general/metrics-general] - [General Guidelines](#general-guidelines) * [Name Reuse Prohibition](#name-reuse-prohibition) * [Units](#units) - * [Pluralization](#pluralization) - + [Use `count` Instead of Pluralization](#use-count-instead-of-pluralization) + * [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) + + [Pluralization](#pluralization) + + [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + + [Do not use `total`](#do-not-use-total) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) * [Instrument Naming](#instrument-naming) * [Instrument Units](#instrument-units) @@ -99,7 +101,9 @@ When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the [OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/compatibility/prometheus_and_openmetrics.md). -### Pluralization +### Naming rules for Counters and UpDownCounters + +#### Pluralization Metric names SHOULD NOT be pluralized, unless the value being recorded represents discrete instances of a @@ -114,7 +118,7 @@ should not be pluralized, even if many data points are recorded. * `system.paging.faults`, `system.disk.operations`, and `system.network.packets` should be pluralized, even if only a single data point is recorded. -#### Use `count` Instead of Pluralization +#### Use `count` Instead of Pluralization for UpDownCounters If the value being recorded represents the count of concepts signified by the namespace then the metric should be named `count` (within its namespace). @@ -125,6 +129,14 @@ to the processes then to represent the count of the processes we can have a metr `system.processes.count`. The suffix `count` here indicates that it is the count of `system.processes`. +#### Do not use `total` + +UpDownCounters SHOULD NOT use `_total` because then they will look like +monotonic sums. + +Counters SHOULD NOT append `_total` either because then their meaning will +be confusing in delta backends. + ## General Metric Semantic Conventions **Status**: [Mixed][DocumentStatus] From 97e92be74714f057739f4cc68448452a03b43068 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Jul 2023 09:21:07 -0400 Subject: [PATCH 25/44] [editorial][CI] Ensure markdownlint has proper exit status (#210) Co-authored-by: Josh Suereth --- gulpfile.js | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/gulpfile.js b/gulpfile.js index a42fd496e5..b01927ecc0 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -4,8 +4,8 @@ const markdownlint = require("markdownlint"); const yaml = require("js-yaml"); const fs = require("fs"); -let fileCount = 0, - issueCount = 0; +let numFilesProcessed = 0, + numFilesWithIssues = 0; function markdownLintFile(file, encoding, callback) { const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); @@ -33,9 +33,11 @@ function markdownLintFile(file, encoding, callback) { .join("\n"); if (resultString) { console.log(resultString); - issueCount++; + numFilesWithIssues++; + // Don't report an error yet so that other files can be checked: + // callback(new Error('...')); } - fileCount++; + numFilesProcessed++; callback(null, file); }); } @@ -47,11 +49,13 @@ function lintMarkdown() { .src(markdownFiles) .pipe(through2.obj(markdownLintFile)) .on("end", () => { - console.log( - `Processed ${fileCount} file${ - fileCount == 1 ? "" : "s" - }, ${issueCount} had issues.`, - ); + const fileOrFiles = "file" + (numFilesProcessed == 1 ? "" : "s"); + const msg = `Processed ${numFilesProcessed} ${fileOrFiles}, ${numFilesWithIssues} had issues.`; + if (numFilesWithIssues > 0) { + throw new Error(msg); + } else { + console.log(msg); + } }); } From c4b58a40ec18ce4577215d02c40eb9efc55eab9c Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 28 Jul 2023 08:26:16 -0400 Subject: [PATCH 26/44] Update contributing documentation for restructuring of repository (#216) Co-authored-by: Johannes Tax Co-authored-by: Armin Ruech --- CONTRIBUTING.md | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc249e0823..5721670ffa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,10 +11,51 @@ requirements and recommendations. Before you can contribute, you will need to sign the [Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf). -## TODO +## How to Contribute + +When contributing to semantic conventions, it's important to understand a few +key, but non-obvious, aspects: + +- All attributes, metrics, etc. are formally defined in YAML files under + the `model/` directory. +- All descriptions, normative language are defined in the `docs/` + directory. + - We provide tooling to generate Markdown documentation from the formal + YAML definitons. See [Yaml to Markdown](#yaml-to-markdown). + - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/). + You will see ` +``` + +When creating new pages, you should provide the `linkTitle` attribute. This is used +to generate the navigation bar on the website, and will be listed relative to the +"parent" document. + +## Automation + +Semantic Conventions provides a set of automated tools for general development. ### Consistency Checks From a46db0f4a60ce7c834ff87d506e94a157a83509f Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 28 Jul 2023 09:29:09 -0400 Subject: [PATCH 27/44] Re-enable the schema check to look at the website. (#217) --- internal/tools/schema_check.sh | 58 +++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 50c8d5e724..d6f0efa4fc 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -11,19 +11,37 @@ BUILD_TOOL_SCHEMAS_VERSION=0.18.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") -root_dir=$PWD -schemas_dir=$root_dir/schemas - -# Find all version sections in CHANGELOG that start with a number in 1..9 range. -grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while read ver; do - if [[ " ${skip_versions[*]} " == *" $ver "* ]]; then - # Skip this version, it does not need a schema file. - continue +# Verifies remote avilability of a schema file. +# +# If the schema file is available for download, THEN we make sure it is exactly +# what is in the repository. If the file is not available for download, +# we pass this check. This is to allow releases to be checked in, where +# a new version is specified but hasn't propagated to the website yet. +# +# Args: +# 1 - version number +verify_remote_availability() { + local ver="$1" + echo -n "Ensure published schema file https://opentelemetry.io/schemas/$ver matches local copy... " + if curl --fail --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver 2>/dev/null; then + diff verify$ver $file && echo "OK, matches" \ + || (echo "Incorrect!" && exit 3) + else + echo "Not found" fi + rm verify$ver +} +# Verifies remote avilability of a schema file in the current repository. +# +# Args: +# 1 - version number +verify_local_availability() { + local ver="$1" + file="$schemas_dir/$ver" echo -n "Ensure schema file $file exists... " - + # Check that the schema for the version exists. if [ -f "$file" ]; then echo "OK, exists." @@ -31,16 +49,20 @@ grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while re echo "FAILED: $file does not exist. The schema file must exist because the version is declared in CHANGELOG.md." exit 3 fi +} + +root_dir=$PWD +schemas_dir=$root_dir/schemas + +# Find all version sections in CHANGELOG that start with a number in 1..9 range. +grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while read ver; do + if [[ " ${skip_versions[*]} " == *" $ver "* ]]; then + # Skip this version, it does not need a schema file. + continue + fi - # Schema file will no be served directly from this repository when linked - # into opentelemetry.io. We disable this for now and need to move the check - # into the website. - # curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver - # - # diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \ - # || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3) - # - # rm verify$ver + verify_local_availability "$ver" + verify_remote_availability "$ver" done # Now check the content of all schema files in the ../shemas directory. From 1c4e58f73298ee92a93a31845b885b7318772d21 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 1 Aug 2023 04:29:43 -0700 Subject: [PATCH 28/44] Add Alexander Wert as an Approver (#220) --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 28ddc8967e..73e784ec82 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/open-telemetry/teams/specs-semconv-approvers)): +- [Alexander Wert](https://github.com/AlexanderWert), Elastic - [Christian Neumüller](https://github.com/Oberon00), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian - [Joao Grassi](https://github.com/joaopgrassi), Dynatrace @@ -29,8 +30,8 @@ _Find more about the approver role in [community repository](https://github.com/ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers)): -- [Josh Suereth](https://github.com/jsuereth) - [Armin Ruech](https://github.com/arminru) +- [Josh Suereth](https://github.com/jsuereth) - [Reiley Yang](https://github.com/reyang) _Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._ From ff064a48455e6937e20f8b6e24065799a3579aae Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Tue, 1 Aug 2023 14:08:29 +0200 Subject: [PATCH 29/44] Bump semantic conventions tooling to v0.20.0 (#225) Co-authored-by: Josh Suereth --- .vscode/settings.json | 2 +- Makefile | 2 +- internal/tools/schema_check.sh | 2 +- model/README.md | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index c216d9b9ef..89d895f2f4 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.17.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.20.0/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index 4d04b73d8f..0a7bed5ae5 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.19.0 +SEMCONVGEN_VERSION=0.20.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index d6f0efa4fc..179ca4087b 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.18.0 +BUILD_TOOL_SCHEMAS_VERSION=0.20.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") diff --git a/model/README.md b/model/README.md index a6c52ba625..b8afe3e506 100644 --- a/model/README.md +++ b/model/README.md @@ -14,12 +14,12 @@ Semantic conventions for the spec MUST adhere to the [attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md), and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.20.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.20.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -30,7 +30,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.20.0/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. From 0cf0e8da574b4ad9b9a07bf80e13b6445d1d3362 Mon Sep 17 00:00:00 2001 From: Ben B Date: Tue, 1 Aug 2023 17:46:45 +0200 Subject: [PATCH 30/44] Add system.cpu.physical.count and system.cpu.logical.count metrics (#99) Co-authored-by: Pablo Baeyens Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Dmitrii Anoshin Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 ++ docs/system/system-metrics.md | 14 ++++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e60ef60c1d..7ec2227460 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -117,6 +117,8 @@ Note: This is the first release of Semantic Conventions separate from the Specif ([#133](https://github.com/open-telemetry/semantic-conventions/pull/133)) - Add markdown file for url semantic conventions ([#174](https://github.com/open-telemetry/semantic-conventions/pull/174)) +- Add `system.cpu.physical.count` and `system.cpu.logical.count` metrics. + ([#99](https://github.com/open-telemetry/opentelemetry-specification/pull/99)) ## v1.20.0 (2023-04-07) diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 3882a55788..2f71ef86af 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -33,12 +33,14 @@ instruments not explicitly defined in the specification. **Description:** System level processor metrics. -| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | -| system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number [0..n-1] | -| system.cpu.utilization | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of CPUs | 1 | Gauge | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number (0..n) | +| Name | Description | Units | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | +| system.cpu.time | Seconds each logical CPU spent on each mode | s | Counter | Double | state | idle, user, system, interrupt, etc. | +| | | | | | cpu | Logical CPU number [0..n-1] | +| system.cpu.utilization | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs | 1 | Gauge | Double | state | idle, user, system, interrupt, etc. | +| | | | | | cpu | Logical CPU number (0..n) | +| system.cpu.physical.count | Reports the number of actual physical processor cores on the hardware | {cpu} | UpDownCounter | Int64 | | | +| system.cpu.logical.count | Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking | {cpu} | UpDownCounter | Int64 | | | ### `system.memory.` - Memory metrics From 740ebd6d990ad1adb9b5f4084dbe24f9b630ff96 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 1 Aug 2023 09:20:58 -0700 Subject: [PATCH 31/44] Add PR template (#223) --- .github/PULL_REQUEST_TEMPLATE.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..40f8193207 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,13 @@ +Fixes # + +## Changes + +Please provide a brief description of the changes here. + +Note: if the PR is touching an area that is not listed in the [existing areas](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md), or the area does not have sufficient [domain experts coverage](https://github.com/open-telemetry/semantic-conventions/blob/main/.github/CODEOWNERS), the PR might be tagged as [experts needed](https://github.com/open-telemetry/semantic-conventions/labels/experts%20needed) and move slowly until experts are identified. + +## Merge requirement checklist + +* [ ] [CONTRIBUTING.md](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md) guidelines followed. +* [ ] [CHANGELOG.md](https://github.com/open-telemetry/semantic-conventions/blob/main/CHANGELOG.md) updated for non-trivial changes. +* [ ] [schema-next.yaml](https://github.com/open-telemetry/semantic-conventions/blob/main/schema-next.yaml) updated with changes to existing conventions. From 6561f68a57ab1ca243b7b550d64983a2dd305551 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 1 Aug 2023 22:30:10 +0200 Subject: [PATCH 32/44] Generate database metrics semconv from YAML (#90) --- docs/database/database-metrics.md | 191 +++++++++++++++++++++++----- model/metrics/database-metrics.yaml | 107 ++++++++++++++++ 2 files changed, 265 insertions(+), 33 deletions(-) create mode 100644 model/metrics/database-metrics.yaml diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 7a24a76e98..047ec6651d 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -8,56 +8,181 @@ linkTitle: Metrics The conventions described in this section are specific to SQL and NoSQL clients. -**Disclaimer:** These are initial database client metric instruments and attributes but more may be added in the future. +**Disclaimer:** These are initial database client metric instruments +and attributes but more may be added in the future. -- [Metric Instruments](#metric-instruments) - * [Connection pools](#connection-pools) +- [Connection pools](#connection-pools) + * [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage) + * [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax) + * [Metric: `db.client.connections.idle.min`](#metric-dbclientconnectionsidlemin) + * [Metric: `db.client.connections.max`](#metric-dbclientconnectionsmax) + * [Metric: `db.client.connections.pending_requests`](#metric-dbclientconnectionspending_requests) + * [Metric: `db.client.connections.timeouts`](#metric-dbclientconnectionstimeouts) + * [Metric: `db.client.connections.create_time`](#metric-dbclientconnectionscreate_time) + * [Metric: `db.client.connections.wait_time`](#metric-dbclientconnectionswait_time) + * [Metric: `db.client.connections.use_time`](#metric-dbclientconnectionsuse_time) -## Metric Instruments +## Connection pools -The following metric instruments MUST be used to describe database client operations. They MUST be of the specified type -and units. +The following metric instruments describe database client connection pool operations. -### Connection pools +### Metric: `db.client.connections.usage` -Below is a table of database client connection pool metric instruments that MUST be used by connection pool -instrumentations: +This metric is [required][MetricRequired]. -| Name | Instrument | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| -| `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. | + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.usage` | UpDownCounter | `{connection}` | The number of connections that are currently in state described by the `state` attribute | + -All `db.client.connections.usage` measurements MUST include the following attribute: + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `state` | string | The state of a connection in the pool | `idle` | Required | -| Name | Type | Description | Examples | Requirement Level | -|---------|--------|------------------------------------------------------------------------------|----------|-------------------| -| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Required | +`state` MUST be one of the following: -Instrumentation libraries for database client connection pools that collect data for the following data MUST use the -following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments -MUST NOT be used. +| Value | Description | +|---|---| +| `idle` | idle | +| `used` | used | + +### Metric: `db.client.connections.idle.max` -| Name | Instrument ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| -| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | -| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | -| `db.client.connections.max` | UpDownCounter | connections | `{connection}` | The maximum number of open connections allowed. | -| `db.client.connections.pending_requests` | UpDownCounter | requests | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool. | -| `db.client.connections.timeouts` | Counter | timeouts | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool. | -| `db.client.connections.create_time` | Histogram | milliseconds | `ms` | The time it took to create a new connection. | -| `db.client.connections.wait_time` | Histogram | milliseconds | `ms` | The time it took to obtain an open connection from the pool. | -| `db.client.connections.use_time` | Histogram | milliseconds | `ms` | The time between borrowing a connection and returning it to the pool. | +This metric is [recommended][MetricRecommended]. -Below is a table of the attributes that MUST be included on all connection pool measurements: + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.idle.max` | UpDownCounter | `{connection}` | The maximum number of idle open connections allowed | + -| Name | Type | Description | Examples | Requirement Level | -|-------------|--------|------------------------------------------------------------------------------|----------------|-------------------| -| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used. | `myDataSource` | Required | + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.idle.min` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.idle.min` | UpDownCounter | `{connection}` | The minimum number of idle open connections allowed | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.max` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.max` | UpDownCounter | `{connection}` | The maximum number of open connections allowed | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.pending_requests` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.pending_requests` | UpDownCounter | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.timeouts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.timeouts` | Counter | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.create_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.create_time` | Histogram | `ms` | The time it took to create a new connection | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.wait_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.wait_time` | Histogram | `ms` | The time it took to obtain an open connection from the pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + + +### Metric: `db.client.connections.use_time` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `db.client.connections.use_time` | Histogram | `ms` | The time between borrowing a connection and returning it to the pool | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#required +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml new file mode 100644 index 0000000000..fdb6a0ce2a --- /dev/null +++ b/model/metrics/database-metrics.yaml @@ -0,0 +1,107 @@ +groups: + - id: attributes.db + type: attribute_group + brief: Describes Database attributes + attributes: + - id: state + type: + allow_custom_values: false + members: + - id: idle + value: 'idle' + - id: used + value: 'used' + requirement_level: required + brief: "The state of a connection in the pool" + examples: ["idle"] + - id: pool.name + type: string + requirement_level: required + brief: > + The name of the connection pool; unique within the instrumented application. + In case the connection pool implementation does not provide a name, + then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) + should be used + examples: ["myDataSource"] + + - id: metric.db.client.connections.usage + type: metric + metric_name: db.client.connections.usage + brief: "The number of connections that are currently in state described by the `state` attribute" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: state + - ref: pool.name + + - id: metric.db.client.connections.idle.max + type: metric + metric_name: db.client.connections.idle.max + brief: "The maximum number of idle open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.idle.min + type: metric + metric_name: db.client.connections.idle.min + brief: "The minimum number of idle open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.max + type: metric + metric_name: db.client.connections.max + brief: "The maximum number of open connections allowed" + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.pending_requests + type: metric + metric_name: db.client.connections.pending_requests + brief: "The number of pending requests for an open connection, cumulative for the entire pool" + instrument: updowncounter + unit: "{request}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.timeouts + type: metric + metric_name: db.client.connections.timeouts + brief: "The number of connection timeouts that have occurred trying to obtain a connection from the pool" + instrument: counter + unit: "{timeout}" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.create_time + type: metric + metric_name: db.client.connections.create_time + brief: "The time it took to create a new connection" + instrument: histogram + unit: "ms" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.wait_time + type: metric + metric_name: db.client.connections.wait_time + brief: "The time it took to obtain an open connection from the pool" + instrument: histogram + unit: "ms" + attributes: + - ref: pool.name + + - id: metric.db.client.connections.use_time + type: metric + metric_name: db.client.connections.use_time + brief: "The time between borrowing a connection and returning it to the pool" + instrument: histogram + unit: "ms" + attributes: + - ref: pool.name From a491f8260d137e00f7672664a5a0710bbdf4188f Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 2 Aug 2023 19:22:58 +0200 Subject: [PATCH 33/44] Generate RPC metrics from YAML (#93) --- docs/rpc/rpc-metrics.md | 137 ++++++++++++++++++++++++++++----- model/metrics/rpc-metrics.yaml | 115 +++++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 18 deletions(-) create mode 100644 model/metrics/rpc-metrics.yaml diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index aaa3647ad3..98d444be96 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -18,7 +18,17 @@ metrics can be filtered for finer grain analysis. - [Metric instruments](#metric-instruments) * [RPC Server](#rpc-server) + + [Metric: `rpc.server.duration`](#metric-rpcserverduration) + + [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize) + + [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize) + + [Metric: `rpc.server.requests_per_rpc`](#metric-rpcserverrequests_per_rpc) + + [Metric: `rpc.server.responses_per_rpc`](#metric-rpcserverresponses_per_rpc) * [RPC Client](#rpc-client) + + [Metric: `rpc.client.duration`](#metric-rpcclientduration) + + [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize) + + [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize) + + [Metric: `rpc.client.requests_per_rpc`](#metric-rpcclientrequests_per_rpc) + + [Metric: `rpc.client.responses_per_rpc`](#metric-rpcclientresponses_per_rpc) - [Attributes](#attributes) * [Service name](#service-name) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) @@ -59,28 +69,118 @@ MUST be of the specified type and units. ### RPC Server -Below is a table of RPC server metric instruments. +Below is a list of RPC server metric instruments. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.server.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per response in a streaming batch | -| `rpc.server.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.server.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | +#### Metric: `rpc.server.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. **Streaming**: N/A. [1] | + +**[1]:** While streaming RPCs may record this metric as start-of-batch +to end-of-batch, it's hard to interpret in practice. + + +#### Metric: `rpc.server.request.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch | + + +#### Metric: `rpc.server.response.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch | + + +#### Metric: `rpc.server.requests_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | + + +#### Metric: `rpc.server.responses_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | + ### RPC Client -Below is a table of RPC client metric instruments. These apply to traditional -RPC usage, not streaming RPCs. +Below is a list of RPC client metric instruments. +These apply to traditional RPC usage, not streaming RPCs. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.client.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | +#### Metric: `rpc.client.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC **Streaming**: N/A. [1] | + +**[1]:** While streaming RPCs may record this metric as start-of-batch +to end-of-batch, it's hard to interpret in practice. + + +#### Metric: `rpc.client.request.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch | + + +#### Metric: `rpc.client.response.size` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch | + + +#### Metric: `rpc.client.requests_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | + + +#### Metric: `rpc.client.responses_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs | + ## Attributes @@ -146,4 +246,5 @@ More specific Semantic Conventions are defined for the following RPC technologie * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml new file mode 100644 index 0000000000..38755d4bf2 --- /dev/null +++ b/model/metrics/rpc-metrics.yaml @@ -0,0 +1,115 @@ +groups: + # TODO: Should we list the attributes on each metric + # OR leave a single table like it is today? Since all attributes are applied + # to all metrics, the repetition of them bloats the page + - id: attributes.metrics.rpc + type: attribute_group + brief: "Describes RPC metric attributes." + attributes: + - ref: rpc.system + - ref: rpc.service + - ref: rpc.method + - ref: network.transport + - ref: network.type + - ref: server.address + - ref: server.port + - ref: server.socket.address + - ref: server.socket.port + + # RPC Server metrics + - id: metric.rpc.server.duration + type: metric + metric_name: rpc.server.duration + brief: > + Measures the duration of inbound RPC. + **Streaming**: N/A. + instrument: histogram + unit: "ms" + note: | + While streaming RPCs may record this metric as start-of-batch + to end-of-batch, it's hard to interpret in practice. + + - id: metric.rpc.server.request.size + type: metric + metric_name: rpc.server.request.size + brief: > + Measures the size of RPC request messages (uncompressed). + **Streaming**: Recorded per message in a streaming batch + instrument: histogram + unit: "By" + + - id: metric.rpc.server.response.size + type: metric + metric_name: rpc.server.response.size + brief: > + Measures the size of RPC response messages (uncompressed). + **Streaming**: Recorded per response in a streaming batch + instrument: histogram + unit: "By" + + - id: metric.rpc.server.requests_per_rpc + type: metric + metric_name: rpc.server.requests_per_rpc + brief: > + Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. + **Streaming**: This metric is required for server and client streaming RPCs + instrument: histogram + unit: "{count}" + + - id: metric.rpc.server.responses_per_rpc + type: metric + metric_name: rpc.server.responses_per_rpc + brief: > + Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. + **Streaming**: This metric is required for server and client streaming RPCs + instrument: histogram + unit: "{count}" + + # RPC Client metrics + - id: metric.rpc.client.duration + type: metric + metric_name: rpc.client.duration + brief: > + Measures the duration of outbound RPC + **Streaming**: N/A. + instrument: histogram + unit: "ms" + note: | + While streaming RPCs may record this metric as start-of-batch + to end-of-batch, it's hard to interpret in practice. + + - id: metric.rpc.client.request.size + type: metric + metric_name: rpc.client.request.size + brief: > + Measures the size of RPC request messages (uncompressed). + **Streaming**: Recorded per message in a streaming batch + instrument: histogram + unit: "By" + + - id: metric.rpc.client.response.size + type: metric + metric_name: rpc.client.response.size + brief: > + Measures the size of RPC response messages (uncompressed). + **Streaming**: Recorded per response in a streaming batch + instrument: histogram + unit: "By" + + - id: metric.rpc.client.requests_per_rpc + type: metric + metric_name: rpc.client.requests_per_rpc + brief: > + Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. + **Streaming**: This metric is required for server and client streaming RPCs + instrument: histogram + unit: "{count}" + + - id: metric.rpc.client.responses_per_rpc + type: metric + metric_name: rpc.client.responses_per_rpc + brief: > + Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. + **Streaming**: This metric is required for server and client streaming RPCs + instrument: histogram + unit: "{count}" From 790eac956f04ee6eed8a4ab0c9535b520c35216b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 3 Aug 2023 10:26:43 -0700 Subject: [PATCH 34/44] Rename `http.*.duration` to `http.*.request.duration` (#224) --- CHANGELOG.md | 5 ++++- docs/general/metrics.md | 2 +- docs/http/http-metrics.md | 20 ++++++++++---------- model/metrics/http.yaml | 8 ++++---- schema-next.yaml | 6 ++++++ 5 files changed, 25 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ec2227460..9b633c9659 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,10 @@ release. ([#95](https://github.com/open-telemetry/semantic-conventions/pull/95)) - Update `.count` metric naming convention so that it only applies to UpDownCounters, and add that `.total` should not be used by either Counters or UpDownCounters - ([#107](https://github.com/open-telemetry/opentelemetry-specification/pull/107)) + ([#107](https://github.com/open-telemetry/semantic-conventions/pull/107)) +- BREAKING: Rename `http.client.duration` and `http.server.duration` metrics to + `http.client.request.duration` and `http.server.request.duration` respectively. + ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224)) ## v1.21.0 (2023-07-13) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 3ba128a273..938a5e73e1 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -113,7 +113,7 @@ question is a non-unit (like `{fault}` or `{operation}`). Examples: -* `system.filesystem.utilization`, `http.server.duration`, and `system.cpu.time` +* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time` should not be pluralized, even if many data points are recorded. * `system.paging.faults`, `system.disk.operations`, and `system.network.packets` should be pluralized, even if only a single data point is recorded. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 502d9e0a14..fe9c4da823 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -15,12 +15,12 @@ operations. By adding HTTP attributes to metric events it allows for finely tune - [HTTP Server](#http-server) - * [Metric: `http.server.duration`](#metric-httpserverduration) + * [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) * [Metric: `http.server.request.size`](#metric-httpserverrequestsize) * [Metric: `http.server.response.size`](#metric-httpserverresponsesize) - [HTTP Client](#http-client) - * [Metric: `http.client.duration`](#metric-httpclientduration) + * [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) * [Metric: `http.client.request.size`](#metric-httpclientrequestsize) * [Metric: `http.client.response.size`](#metric-httpclientresponsesize) @@ -53,7 +53,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune ## HTTP Server -### Metric: `http.server.duration` +### Metric: `http.server.request.duration` **Status**: [Experimental, Feature-freeze][DocumentStatus] @@ -65,13 +65,13 @@ This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.server.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | +| `http.server.request.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | @@ -364,7 +364,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi ## HTTP Client -### Metric: `http.client.duration` +### Metric: `http.client.request.duration` **Status**: [Experimental, Feature-freeze][DocumentStatus] @@ -376,13 +376,13 @@ This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.duration` | Histogram | `s` | Measures the duration of outbound HTTP requests. | +| `http.client.request.duration` | Histogram | `s` | Measures the duration of outbound HTTP requests. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 385242ddbb..813179a005 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -48,9 +48,9 @@ groups: - ref: network.protocol.version - ref: server.socket.address - - id: metric.http.server.duration + - id: metric.http.server.request.duration type: metric - metric_name: http.server.duration + metric_name: http.server.request.duration brief: "Measures the duration of inbound HTTP requests." instrument: histogram unit: "s" @@ -110,9 +110,9 @@ groups: unit: "By" extends: metric_attributes.http.server - - id: metric.http.client.duration + - id: metric.http.client.request.duration type: metric - metric_name: http.client.duration + metric_name: http.client.request.duration brief: "Measures the duration of outbound HTTP requests." instrument: histogram unit: "s" diff --git a/schema-next.yaml b/schema-next.yaml index 37d35efc84..14e82faac1 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,12 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/1.21.0 versions: next: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration 1.21.0: spans: changes: From 2f4d8b4db428468a141cefbcb32d7f9a8955c926 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Sun, 6 Aug 2023 13:50:56 -0700 Subject: [PATCH 35/44] HTTP version should be 2 and 3 instead of 2.0 and 3.0 (#228) --- CHANGELOG.md | 2 ++ docs/http/http-spans.md | 2 +- model/http-common.yaml | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b633c9659..cf8ad93306 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. - BREAKING: Rename `http.client.duration` and `http.server.duration` metrics to `http.client.request.duration` and `http.server.request.duration` respectively. ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224)) +- Update HTTP `network.protocol.version` examples to match HTTP RFCs. + ([#228](https://github.com/open-telemetry/semantic-conventions/pull/228)) ## v1.21.0 (2023-07-13) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 946e1be2ca..dd15d32552 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -101,7 +101,7 @@ sections below. | `http.response.body.size` | int | 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. | `3495` | Recommended | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2`; `3` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | | [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | diff --git a/model/http-common.yaml b/model/http-common.yaml index 682b2cb984..9db84ce583 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -68,7 +68,7 @@ groups: requirement_level: recommended: if not default (`http`). - ref: network.protocol.version - examples: ['1.0', '1.1', '2.0'] + examples: ['1.0', '1.1', '2', '3'] - id: attributes.http.client prefix: http From 94b653e216edd949cdca03176bfc5ffc7ac26d88 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Mon, 7 Aug 2023 17:27:53 +0200 Subject: [PATCH 36/44] Generate FaaS metrics semconv from YAML (#88) --- CHANGELOG.md | 4 + docs/faas/faas-metrics.md | 275 ++++++++++++++++++++++++++++---- docs/faas/faas-spans.md | 36 ++--- model/faas-common.yaml | 77 +++++++++ model/metrics/faas-metrics.yaml | 81 ++++++++++ model/trace/faas.yaml | 94 ++--------- 6 files changed, 438 insertions(+), 129 deletions(-) create mode 100644 model/faas-common.yaml create mode 100644 model/metrics/faas-metrics.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index cf8ad93306..10ee6bcda1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,10 @@ release. ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224)) - Update HTTP `network.protocol.version` examples to match HTTP RFCs. ([#228](https://github.com/open-telemetry/semantic-conventions/pull/228)) +- Generate FaaS metric semantic conventions from YAML. + ([#88](https://github.com/open-telemetry/semantic-conventions/pull/88)) + The conventions cover metrics that are recorded by the FaaS itself and not by + clients invoking them. ## v1.21.0 (2023-07-13) diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 376ec3dc7d..ab1f395c13 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -13,15 +13,21 @@ The conventions described in this section are FaaS (function as a service) speci metric events about those operations will be generated and reported to provide insights into the operations. By adding FaaS attributes to metric events it allows for finely tuned filtering. -**Disclaimer:** These are initial FaaS metric instruments and attributes but more may be added in the future. - - [Metric Instruments](#metric-instruments) - * [FaaS Invocations](#faas-invocations) -- [Attributes](#attributes) + * [FaaS Instance](#faas-instance) + + [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration) + + [Metric: `faas.init_duration`](#metric-faasinit_duration) + + [Metric: `faas.coldstarts`](#metric-faascoldstarts) + + [Metric: `faas.errors`](#metric-faaserrors) + + [Metric: `faas.invocations`](#metric-faasinvocations) + + [Metric: `faas.timeouts`](#metric-faastimeouts) + + [Metric: `faas.mem_usage`](#metric-faasmem_usage) + + [Metric: `faas.cpu_usage`](#metric-faascpu_usage) + + [Metric: `faas.net_io`](#metric-faasnet_io) - [References](#references) * [Metric References](#metric-references) @@ -29,45 +35,245 @@ operations. By adding FaaS attributes to metric events it allows for finely tune ## Metric Instruments -The following metric instruments MUST be used to describe FaaS operations. They MUST be of the specified -type and units. +The following metric instruments describe FaaS operations. + +### FaaS Instance + +The following metrics are recorded by the FaaS instance. + +#### Metric: `faas.invoke_duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.invoke_duration` | Histogram | `ms` | Measures the duration of the function's logic execution | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.init_duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.init_duration` | Histogram | `ms` | Measures the duration of the function's initialization, such as a cold start | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.coldstarts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.coldstarts` | Counter | `{coldstart}` | Number of invocation cold starts | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.errors` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.errors` | Counter | `{error}` | Number of invocation errors | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.invocations` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.invocations` | Counter | `{invocation}` | Number of successful invocations | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.timeouts` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.timeouts` | Counter | `{timeout}` | Number of invocation timeouts | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.mem_usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.mem_usage` | Histogram | `By` | Distribution of max memory usage per invocation | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + + +#### Metric: `faas.cpu_usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.cpu_usage` | Histogram | `ms` | Distribution of CPU usage per invocation | + -### FaaS Invocations + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | -Below is a table of FaaS invocation metric instruments. +`faas.trigger` MUST be one of the following: -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| -| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | -| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | -| `faas.coldstarts` | Counter | default unit | `{coldstart}` | Number of invocation cold starts. | -| `faas.errors` | Counter | default unit | `{error}` | Number of invocation errors. | -| `faas.invocations` | Counter | default unit | `{invocation}` | Number of successful invocations. | -| `faas.timeouts` | Counter | default unit | `{timeout}` | Number of invocation timeouts. | +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + -Optionally, when applicable: +#### Metric: `faas.net_io` -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | -|------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------| -| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | -| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of CPU usage per invocation | -| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation | +This metric is [recommended][MetricRecommended]. -## Attributes + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.net_io` | Histogram | `By` | Distribution of net I/O usage per invocation | + -Below is a table of the attributes to be included on FaaS metric events. + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | -| Name | Requirement Level | Notes and examples | -|-------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------| -| `faas.trigger` | Required | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` | -| `faas.invoked_name` | Required | Name of the invoked function. Example: `my-function` | -| `faas.invoked_provider` | Required | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | -| `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | +`faas.trigger` MUST be one of the following: -More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](faas-spans.md). -For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../resource/faas.md). -Outgoing FaaS invocations are identified using the `faas.invoked_*` attributes above. -`faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS invocation events only. +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + ## References @@ -83,3 +289,4 @@ FaaS providers. This list is not exhaustive. * [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/) [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 2a06a3c1ec..8a90312273 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -38,24 +38,14 @@ Span `name` should be set to the function name being executed. Depending on the If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | | `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | -| [`cloud.resource_id`](../resource/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| [`cloud.resource_id`](../resource/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [1] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. [2] | `datasource` | Recommended | -**[1]:** For the server/consumer span on the incoming side, -`faas.trigger` MUST be set. - -Clients invoking FaaS instances usually cannot set `faas.trigger`, -since they would typically need to look in the payload to determine -the event type. If clients set it, it should be the same as the -trigger that corresponding incoming would have (i.e., this has -nothing to do with the underlying transport used to make the API -call to invoke the lambda, which is often HTTP). - -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, +**[1]:** On some cloud providers, it may not be possible to determine the full ID at startup, so it may be necessary to set `cloud.resource_id` as a span attribute instead. The exact value to use for `cloud.resource_id` depends on the cloud provider. @@ -73,14 +63,24 @@ The following well-known definitions MUST be used if you set this attribute and This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider. +**[2]:** For the server/consumer span on the incoming side, +`faas.trigger` MUST be set. + +Clients invoking FaaS instances usually cannot set `faas.trigger`, +since they would typically need to look in the payload to determine +the event type. If clients set it, it should be the same as the +trigger that corresponding incoming would have (i.e., this has +nothing to do with the underlying transport used to make the API +call to invoke the lambda, which is often HTTP). + `faas.trigger` MUST be one of the following: | Value | Description | |---|---| -| `datasource` | A response to some data source operation such as a database or filesystem read/write. | +| `datasource` | A response to some data source operation such as a database or filesystem read/write | | `http` | To provide an answer to an inbound HTTP request | -| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | -| `timer` | A function is scheduled to be executed regularly. | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | | `other` | If none of the others apply | @@ -158,7 +158,7 @@ The values reported by the client for the attributes listed below SHOULD be equa the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], which the invoked FaaS instance reports about itself, if it's instrumented. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | diff --git a/model/faas-common.yaml b/model/faas-common.yaml new file mode 100644 index 0000000000..7f903bb57f --- /dev/null +++ b/model/faas-common.yaml @@ -0,0 +1,77 @@ +groups: + - id: attributes.faas.common + type: attribute_group + brief: "Describes FaaS attributes." + prefix: faas + attributes: + - id: trigger + brief: 'Type of the trigger which caused this function invocation.' + type: + allow_custom_values: false + members: + - id: datasource + value: 'datasource' + brief: 'A response to some data source operation such as a database or filesystem read/write' + - id: http + value: 'http' + brief: 'To provide an answer to an inbound HTTP request' + - id: pubsub + value: 'pubsub' + brief: 'A function is set to be executed when messages are sent to a messaging system' + - id: timer + value: 'timer' + brief: 'A function is scheduled to be executed regularly' + - id: other + value: 'other' + brief: 'If none of the others apply' + - id: invoked_name + type: string + requirement_level: required + brief: > + The name of the invoked function. + note: > + SHOULD be equal to the `faas.name` resource attribute of the + invoked function. + examples: 'my-function' + - id: invoked_provider + type: + allow_custom_values: true + members: + - id: 'alibaba_cloud' + value: 'alibaba_cloud' + brief: 'Alibaba Cloud' + - id: 'aws' + value: 'aws' + brief: 'Amazon Web Services' + - id: 'azure' + value: 'azure' + brief: 'Microsoft Azure' + - id: 'gcp' + value: 'gcp' + brief: 'Google Cloud Platform' + - id: 'tencent_cloud' + value: 'tencent_cloud' + brief: 'Tencent Cloud' + requirement_level: required + brief: > + The cloud provider of the invoked function. + note: > + SHOULD be equal to the `cloud.provider` resource attribute of the + invoked function. + - id: invoked_region + type: string + requirement_level: + conditionally_required: > + For some cloud providers, like AWS or GCP, the region in which a + function is hosted is essential to uniquely identify the function + and also part of its endpoint. Since it's part of the endpoint + being called, the region is always known to clients. In these cases, + `faas.invoked_region` MUST be set accordingly. If the region is + unknown to the client or not required for identifying the invoked + function, setting `faas.invoked_region` is optional. + brief: > + The cloud region of the invoked function. + note: > + SHOULD be equal to the `cloud.region` resource attribute of the + invoked function. + examples: 'eu-central-1' diff --git a/model/metrics/faas-metrics.yaml b/model/metrics/faas-metrics.yaml new file mode 100644 index 0000000000..6a753a7351 --- /dev/null +++ b/model/metrics/faas-metrics.yaml @@ -0,0 +1,81 @@ +groups: + - id: metric.faas.invoke_duration + type: metric + metric_name: faas.invoke_duration + brief: "Measures the duration of the function's logic execution" + instrument: histogram + unit: "ms" + attributes: + - ref: faas.trigger + + - id: metric.faas.init_duration + type: metric + metric_name: faas.init_duration + brief: "Measures the duration of the function's initialization, such as a cold start" + instrument: histogram + unit: "ms" + attributes: + - ref: faas.trigger + + - id: metric.faas.coldstarts + type: metric + metric_name: faas.coldstarts + brief: "Number of invocation cold starts" + instrument: counter + unit: "{coldstart}" + attributes: + - ref: faas.trigger + + - id: metric.faas.errors + type: metric + metric_name: faas.errors + brief: "Number of invocation errors" + instrument: counter + unit: "{error}" + attributes: + - ref: faas.trigger + + - id: metric.faas.invocations + type: metric + metric_name: faas.invocations + brief: "Number of successful invocations" + instrument: counter + unit: "{invocation}" + attributes: + - ref: faas.trigger + + - id: metric.faas.timeouts + type: metric + metric_name: faas.timeouts + brief: "Number of invocation timeouts" + instrument: counter + unit: "{timeout}" + attributes: + - ref: faas.trigger + + - id: metric.faas.mem_usage + type: metric + metric_name: faas.mem_usage + brief: "Distribution of max memory usage per invocation" + instrument: histogram + unit: "By" + attributes: + - ref: faas.trigger + + - id: metric.faas.cpu_usage + type: metric + metric_name: faas.cpu_usage + brief: "Distribution of CPU usage per invocation" + instrument: histogram + unit: "ms" + attributes: + - ref: faas.trigger + + - id: metric.faas.net_io + type: metric + metric_name: faas.net_io + brief: "Distribution of net I/O usage per invocation" + instrument: histogram + unit: "By" + attributes: + - ref: faas.trigger diff --git a/model/trace/faas.yaml b/model/trace/faas.yaml index d30d41920a..84b7141b38 100644 --- a/model/trace/faas.yaml +++ b/model/trace/faas.yaml @@ -7,8 +7,7 @@ groups: runs without provisioning or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans. attributes: - - id: trigger - brief: 'Type of the trigger which caused this function invocation.' + - ref: faas.trigger note: | For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -19,33 +18,15 @@ groups: trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP). - type: - allow_custom_values: false - members: - - id: datasource - value: 'datasource' - brief: 'A response to some data source operation such as a database or filesystem read/write.' - - id: http - value: 'http' - brief: 'To provide an answer to an inbound HTTP request' - - id: pubsub - value: 'pubsub' - brief: 'A function is set to be executed when messages are sent to a messaging system.' - - id: timer - value: 'timer' - brief: 'A function is scheduled to be executed regularly.' - - id: other - value: 'other' - brief: 'If none of the others apply' - id: invocation_id type: string brief: 'The invocation ID of the current function invocation.' examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' - ref: cloud.resource_id + - id: faas_span.datasource prefix: faas.document type: span - extends: faas_span brief: > Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. @@ -90,24 +71,23 @@ groups: - id: faas_span.http type: span - extends: faas_span brief: > Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. constraints: - include: trace.http.server + attributes: [] - id: faas_span.pubsub type: span - extends: faas_span brief: > Semantic Convention for FaaS set to be executed when messages are sent to a messaging system. constraints: - include: messaging + attributes: [] - id: faas_span.timer - extends: faas_span prefix: faas type: span brief: > @@ -128,7 +108,6 @@ groups: examples: "0/5 * * * ? *" - id: faas_span.in - extends: faas_span span_kind: server prefix: faas type: span @@ -142,63 +121,24 @@ groups: first time (aka cold-start). - ref: faas.trigger requirement_level: required + note: | + For the server/consumer span on the incoming side, + `faas.trigger` MUST be set. + + Clients invoking FaaS instances usually cannot set `faas.trigger`, + since they would typically need to look in the payload to determine + the event type. If clients set it, it should be the same as the + trigger that corresponding incoming would have (i.e., this has + nothing to do with the underlying transport used to make the API + call to invoke the lambda, which is often HTTP). - id: faas_span.out - extends: faas_span span_kind: client prefix: faas type: span brief: > Contains additional attributes for outgoing FaaS spans. attributes: - - id: invoked_name - type: string - requirement_level: required - brief: > - The name of the invoked function. - note: > - SHOULD be equal to the `faas.name` resource attribute of the - invoked function. - examples: 'my-function' - - id: invoked_provider - type: - allow_custom_values: true - members: - - id: 'alibaba_cloud' - value: 'alibaba_cloud' - brief: 'Alibaba Cloud' - - id: 'aws' - value: 'aws' - brief: 'Amazon Web Services' - - id: 'azure' - value: 'azure' - brief: 'Microsoft Azure' - - id: 'gcp' - value: 'gcp' - brief: 'Google Cloud Platform' - - id: 'tencent_cloud' - value: 'tencent_cloud' - brief: 'Tencent Cloud' - requirement_level: required - brief: > - The cloud provider of the invoked function. - note: > - SHOULD be equal to the `cloud.provider` resource attribute of the - invoked function. - - id: invoked_region - type: string - requirement_level: - conditionally_required: > - For some cloud providers, like AWS or GCP, the region in which a - function is hosted is essential to uniquely identify the function - and also part of its endpoint. Since it's part of the endpoint - being called, the region is always known to clients. In these cases, - `faas.invoked_region` MUST be set accordingly. If the region is - unknown to the client or not required for identifying the invoked - function, setting `faas.invoked_region` is optional. - brief: > - The cloud region of the invoked function. - note: > - SHOULD be equal to the `cloud.region` resource attribute of the - invoked function. - examples: 'eu-central-1' + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region From 8dfd92ca9ed9feba0031761c8ae3b8db37bc010b Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Mon, 7 Aug 2023 18:58:19 +0200 Subject: [PATCH 37/44] Re-introduce namespace to describe the original destination (#156) Co-authored-by: Armin Ruech --- CHANGELOG.md | 3 +++ docs/messaging/messaging-spans.md | 30 +++++++++++++++++++++++++++--- model/trace/messaging.yaml | 28 ++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10ee6bcda1..2009f95066 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ release. ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224)) - Update HTTP `network.protocol.version` examples to match HTTP RFCs. ([#228](https://github.com/open-telemetry/semantic-conventions/pull/228)) +- Re-introduce namespace and attributes to describe the original destination messages were + published to (`messaging.destination_publish.*`). + ([#156](https://github.com/open-telemetry/semantic-conventions/pull/156)) - Generate FaaS metric semantic conventions from YAML. ([#88](https://github.com/open-telemetry/semantic-conventions/pull/88)) The conventions cover metrics that are recorded by the FaaS itself and not by diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index cee92e4815..a8a642acff 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -105,6 +105,12 @@ A destination is usually uniquely identified by its name within the messaging system instance. Examples of a destination name would be an URL or a simple one-word identifier. +In some use cases, messages are routed within one or multiple brokers. In such +cases, the destination the message was originally published to is different +from the destination it is being consumed from. When information about the +destination where the message was originally published to is available, consumers +can record them under the `destination_publish` namespace. + Typical examples of destinations include Kafka topics, RabbitMQ queues and topics. ### Message consumption @@ -281,9 +287,8 @@ These attributes should be set to the broker to which the message is sent/from w ### Attribute namespaces - `messaging.message`: Contains attributes that describe individual messages -- `messaging.destination`: Contains attributes that describe the logical entity - messages are published to and received from. - See [Destinations](#destinations) for more details +- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details +- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details - `messaging.batch`: Contains attributes that describe batch operations - `messaging.consumer`: Contains attributes that describe application instance that consumes a message. See [consumer](#consumer) for more details @@ -298,6 +303,25 @@ as described in [Attributes specific to certain messaging systems](#attributes-s ### Consumer attributes +The following additional attributes describe message consumer operations. + +Since messages could be routed by brokers, the destination messages are published +to may not match with the destination they are consumed from. + +If information about the original destination is available on the consumer, +consumer instrumentations SHOULD populate the attributes +under the namespace `messaging.destination_publish.*` + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended | +| `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended | + +**[1]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If +the broker does not have such notion, the original destination name SHOULD uniquely identify the broker. + + The *receive* span is used to track the time used for receiving the message(s), whereas the *process* span(s) track the time for processing the message(s). Note that one or multiple Spans with `messaging.operation` = `process` may often be the children of a Span with `messaging.operation` = `receive`. The distinction between receiving and processing of messages is not always of particular interest or sometimes hidden away in a framework (see the [Message consumption](#message-consumption) section above) and therefore the attribute can be left out. diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 5df3c54698..bb7a768638 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -64,6 +64,34 @@ groups: type: boolean brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + - id: messaging.destination_publish + prefix: messaging.destination_publish + type: attribute_group + brief: > + Semantic convention for attributes that describe the publish messaging destination on broker. + The term Publish Destination refers to the destination the message was originally published to. + These attributes should be used on the consumer side when information about + the publish destination is available and different than the destination message are consumed from. + note: | + Publish destination attributes should be set on publish, receive, + or other spans describing messaging operations. + Destination attributes should be set when the messaging operation handles + single messages. When the operation handles a batch of messages, + the destination attributes should only be applied when the attribute value + applies to all messages in the batch. + In other cases, destination attributes may be set on links. + attributes: + - id: name + type: string + brief: 'The name of the original destination the message was published to' + note: | + The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If + the broker does not have such notion, the original destination name SHOULD uniquely identify the broker. + examples: ['MyQueue', 'MyTopic'] + - id: anonymous + type: boolean + brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' + - id: messaging prefix: messaging type: span From 50cf5942c356f5af9e0df2acad8000dfe50587f6 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 8 Aug 2023 10:17:52 -0700 Subject: [PATCH 38/44] Move Joao Grassi from approver to maintainer (#239) --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 73e784ec82..4b8b2cf6f6 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,6 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope - [Alexander Wert](https://github.com/AlexanderWert), Elastic - [Christian Neumüller](https://github.com/Oberon00), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian -- [Joao Grassi](https://github.com/joaopgrassi), Dynatrace - [Johannes Tax](https://github.com/pyohannes), Grafana Labs - [Liudmila Molkova](https://github.com/lmolkova), Microsoft - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian @@ -30,9 +29,10 @@ _Find more about the approver role in [community repository](https://github.com/ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers)): -- [Armin Ruech](https://github.com/arminru) -- [Josh Suereth](https://github.com/jsuereth) -- [Reiley Yang](https://github.com/reyang) +- [Armin Ruech](https://github.com/arminru), Dynatrace +- [Joao Grassi](https://github.com/joaopgrassi), Dynatrace +- [Josh Suereth](https://github.com/jsuereth), Google +- [Reiley Yang](https://github.com/reyang), Microsoft _Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._ From d550c9872e427a2bb25e8106deb64117208b330f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 10 Aug 2023 09:56:09 -0700 Subject: [PATCH 39/44] Update destination attribute briefs (#243) --- docs/general/attributes.md | 4 ++-- model/destination.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 13e98d5595..289badc7cd 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -221,8 +221,8 @@ Destination fields capture details about the receiver of a network exchange/pack | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended | -| `destination.address` | string | Peer address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended | -| `destination.port` | int | Peer port number | `3389`; `2888` | Recommended | +| `destination.address` | string | Destination address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended | +| `destination.port` | int | Destination port number | `3389`; `2888` | Recommended | **[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. diff --git a/model/destination.yaml b/model/destination.yaml index 2df72bd9f3..a2fd8fd65f 100644 --- a/model/destination.yaml +++ b/model/destination.yaml @@ -16,9 +16,9 @@ groups: note: This value may be a host name, a fully qualified domain name, or another host naming format. - id: address type: string - brief: 'Peer address, for example IP address or UNIX socket name.' + brief: 'Destination address, for example IP address or UNIX socket name.' examples: ['10.5.3.2'] - id: port type: int - brief: 'Peer port number' + brief: 'Destination port number' examples: [3389, 2888] From a6c32022fc1b45902d81ef2c0be1cef7567f375b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 10 Aug 2023 14:23:48 -0700 Subject: [PATCH 40/44] Rename all JVM metrics from process.runtime.jvm.* to jvm.* (#241) --- CHANGELOG.md | 2 + docs/system/runtime-environment-metrics.md | 174 +++++++++--------- ...cess-runtime-jvm-metrics-experimental.yaml | 34 ++-- .../metrics/process-runtime-jvm-metrics.yaml | 54 +++--- schema-next.yaml | 19 ++ 5 files changed, 152 insertions(+), 131 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2009f95066..9089400e69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,8 @@ release. ([#88](https://github.com/open-telemetry/semantic-conventions/pull/88)) The conventions cover metrics that are recorded by the FaaS itself and not by clients invoking them. +- BREAKING: Rename all JVM metrics from `process.runtime.jvm.*` to `jvm.*` + ([#241](https://github.com/open-telemetry/semantic-conventions/pull/241)) ## v1.21.0 (2023-07-13) diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md index 280450102c..03f338b881 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/system/runtime-environment-metrics.md @@ -20,24 +20,24 @@ semantic conventions when instrumenting runtime environments. * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) - [Attributes](#attributes) - [JVM Metrics](#jvm-metrics) - * [Metric: `process.runtime.jvm.memory.usage`](#metric-processruntimejvmmemoryusage) - * [Metric: `process.runtime.jvm.memory.committed`](#metric-processruntimejvmmemorycommitted) - * [Metric: `process.runtime.jvm.memory.limit`](#metric-processruntimejvmmemorylimit) - * [Metric: `process.runtime.jvm.memory.usage_after_last_gc`](#metric-processruntimejvmmemoryusage_after_last_gc) - * [Metric: `process.runtime.jvm.gc.duration`](#metric-processruntimejvmgcduration) - * [Metric: `process.runtime.jvm.threads.count`](#metric-processruntimejvmthreadscount) - * [Metric: `process.runtime.jvm.classes.loaded`](#metric-processruntimejvmclassesloaded) - * [Metric: `process.runtime.jvm.classes.unloaded`](#metric-processruntimejvmclassesunloaded) - * [Metric: `process.runtime.jvm.classes.current_loaded`](#metric-processruntimejvmclassescurrent_loaded) - * [Metric: `process.runtime.jvm.cpu.time`](#metric-processruntimejvmcputime) - * [Metric: `process.runtime.jvm.cpu.recent_utilization`](#metric-processruntimejvmcpurecent_utilization) + * [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage) + * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) + * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) + * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) + * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) + * [Metric: `jvm.threads.count`](#metric-jvmthreadscount) + * [Metric: `jvm.classes.loaded`](#metric-jvmclassesloaded) + * [Metric: `jvm.classes.unloaded`](#metric-jvmclassesunloaded) + * [Metric: `jvm.classes.current_loaded`](#metric-jvmclassescurrent_loaded) + * [Metric: `jvm.cpu.time`](#metric-jvmcputime) + * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) - [JVM Metrics (Experimental)](#jvm-metrics-experimental) - * [Metric: `process.runtime.jvm.memory.init`](#metric-processruntimejvmmemoryinit) - * [Metric: `process.runtime.jvm.system.cpu.utilization`](#metric-processruntimejvmsystemcpuutilization) - * [Metric: `process.runtime.jvm.system.cpu.load_1m`](#metric-processruntimejvmsystemcpuload_1m) - * [Metric: `process.runtime.jvm.buffer.usage`](#metric-processruntimejvmbufferusage) - * [Metric: `process.runtime.jvm.buffer.limit`](#metric-processruntimejvmbufferlimit) - * [Metric: `process.runtime.jvm.buffer.count`](#metric-processruntimejvmbuffercount) + * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) + * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) + * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) + * [Metric: `jvm.buffer.usage`](#metric-jvmbufferusage) + * [Metric: `jvm.buffer.limit`](#metric-jvmbufferlimit) + * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) @@ -75,20 +75,20 @@ consider, for example pthreads vs green thread implementations. ## JVM Metrics -**Description:** Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` +**Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.` -### Metric: `process.runtime.jvm.memory.usage` +### Metric: `jvm.memory.usage` This metric is [recommended][MetricRecommended]. This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | +| `jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | @@ -104,18 +104,18 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | `non_heap` | Non-heap memory | -### Metric: `process.runtime.jvm.memory.committed` +### Metric: `jvm.memory.committed` This metric is [recommended][MetricRecommended]. This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | +| `jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | @@ -131,18 +131,18 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | `non_heap` | Non-heap memory | -### Metric: `process.runtime.jvm.memory.limit` +### Metric: `jvm.memory.limit` This metric is [recommended][MetricRecommended]. This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | +| `jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | @@ -158,18 +158,18 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | `non_heap` | Non-heap memory | -### Metric: `process.runtime.jvm.memory.usage_after_last_gc` +### Metric: `jvm.memory.usage_after_last_gc` This metric is [recommended][MetricRecommended]. This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | +| `jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | @@ -185,7 +185,7 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d | `non_heap` | Non-heap memory | -### Metric: `process.runtime.jvm.gc.duration` +### Metric: `jvm.gc.duration` This metric is [recommended][MetricRecommended]. This metric is obtained by subscribing to @@ -195,13 +195,13 @@ This metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) of `[]` (single bucket histogram capturing count, sum, min, max). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | +| `jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `gc` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | @@ -212,117 +212,117 @@ of `[]` (single bucket histogram capturing count, sum, min, max). **[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). -### Metric: `process.runtime.jvm.threads.count` +### Metric: `jvm.threads.count` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and [`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). Note that this is the number of platform threads (as opposed to virtual threads). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.threads.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | +| `jvm.threads.count` | UpDownCounter | `{thread}` | Number of executing platform threads. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `daemon` | boolean | Whether the thread is daemon or not. | | Recommended | -### Metric: `process.runtime.jvm.classes.loaded` +### Metric: `jvm.classes.loaded` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | +| `jvm.classes.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | - + -### Metric: `process.runtime.jvm.classes.unloaded` +### Metric: `jvm.classes.unloaded` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | +| `jvm.classes.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | - + -### Metric: `process.runtime.jvm.classes.current_loaded` +### Metric: `jvm.classes.current_loaded` This metric is [recommended][MetricRecommended]. This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.current_loaded` | UpDownCounter | `{class}` | Number of classes currently loaded. | +| `jvm.classes.current_loaded` | UpDownCounter | `{class}` | Number of classes currently loaded. | - + -### Metric: `process.runtime.jvm.cpu.time` +### Metric: `jvm.cpu.time` This metric is [recommended][MetricRecommended]. This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuTime()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuTime()) on HotSpot and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuTime()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuTime--) on J9. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | +| `jvm.cpu.time` | Counter | `s` | CPU time used by the process as reported by the JVM. | - + -### Metric: `process.runtime.jvm.cpu.recent_utilization` +### Metric: `jvm.cpu.recent_utilization` This metric is [recommended][MetricRecommended]. This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. Note that the JVM does not provide a definition of what "recent" means. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | +| `jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] | **[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()). - + ## JVM Metrics (Experimental) -**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` +**Description:** Experimental Java Virtual Machine (JVM) metrics captured under `jvm.` -### Metric: `process.runtime.jvm.memory.init` +### Metric: `jvm.memory.init` This metric is [recommended][MetricRecommended]. This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | +| `jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | @@ -338,51 +338,51 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | `non_heap` | Non-heap memory | -### Metric: `process.runtime.jvm.system.cpu.utilization` +### Metric: `jvm.system.cpu.utilization` This metric is [Opt-In][MetricOptIn]. This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html) on J9. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | +| `jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] | **[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()). - + -### Metric: `process.runtime.jvm.system.cpu.load_1m` +### Metric: `jvm.system.cpu.load_1m` This metric is [Opt-In][MetricOptIn]. This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | +| `jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] | **[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()). - + -### Metric: `process.runtime.jvm.buffer.usage` +### Metric: `jvm.buffer.usage` This metric is [recommended][MetricRecommended]. This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | +| `jvm.buffer.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | @@ -390,18 +390,18 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). -### Metric: `process.runtime.jvm.buffer.limit` +### Metric: `jvm.buffer.limit` This metric is [recommended][MetricRecommended]. This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | +| `jvm.buffer.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | @@ -409,18 +409,18 @@ This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://doc **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). -### Metric: `process.runtime.jvm.buffer.count` +### Metric: `jvm.buffer.count` This metric is [recommended][MetricRecommended]. This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | +| `jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | diff --git a/model/metrics/process-runtime-jvm-metrics-experimental.yaml b/model/metrics/process-runtime-jvm-metrics-experimental.yaml index 3956368631..06c8090838 100644 --- a/model/metrics/process-runtime-jvm-metrics-experimental.yaml +++ b/model/metrics/process-runtime-jvm-metrics-experimental.yaml @@ -1,15 +1,15 @@ groups: - - id: metric.process.runtime.jvm.memory.init + - id: metric.jvm.memory.init type: metric - metric_name: process.runtime.jvm.memory.init - extends: attributes.process.runtime.jvm.memory + metric_name: jvm.memory.init + extends: attributes.jvm.memory brief: "Measure of initial memory requested." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.system.cpu.utilization + - id: metric.jvm.system.cpu.utilization type: metric - metric_name: process.runtime.jvm.system.cpu.utilization + metric_name: jvm.system.cpu.utilization brief: "Recent CPU utilization for the whole system as reported by the JVM." note: > The value range is [0.0,1.0]. @@ -19,9 +19,9 @@ groups: instrument: gauge unit: "1" - - id: metric.process.runtime.jvm.system.cpu.load_1m + - id: metric.jvm.system.cpu.load_1m type: metric - metric_name: process.runtime.jvm.system.cpu.load_1m + metric_name: jvm.system.cpu.load_1m brief: "Average CPU load of the whole system for the last minute as reported by the JVM." note: > The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. @@ -31,7 +31,7 @@ groups: instrument: gauge unit: "{run_queue_item}" - - id: attributes.process.runtime.jvm.buffer + - id: attributes.jvm.buffer type: attribute_group brief: "Describes JVM buffer metric attributes." attributes: @@ -42,26 +42,26 @@ groups: Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - id: metric.process.runtime.jvm.buffer.usage + - id: metric.jvm.buffer.usage type: metric - metric_name: process.runtime.jvm.buffer.usage - extends: attributes.process.runtime.jvm.buffer + metric_name: jvm.buffer.usage + extends: attributes.jvm.buffer brief: "Measure of memory used by buffers." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.buffer.limit + - id: metric.jvm.buffer.limit type: metric - metric_name: process.runtime.jvm.buffer.limit - extends: attributes.process.runtime.jvm.buffer + metric_name: jvm.buffer.limit + extends: attributes.jvm.buffer brief: "Measure of total memory capacity of buffers." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.buffer.count + - id: metric.jvm.buffer.count type: metric - metric_name: process.runtime.jvm.buffer.count - extends: attributes.process.runtime.jvm.buffer + metric_name: jvm.buffer.count + extends: attributes.jvm.buffer brief: "Number of buffers in the pool." instrument: updowncounter unit: "{buffer}" diff --git a/model/metrics/process-runtime-jvm-metrics.yaml b/model/metrics/process-runtime-jvm-metrics.yaml index 1721b8e956..b08c3f72d5 100644 --- a/model/metrics/process-runtime-jvm-metrics.yaml +++ b/model/metrics/process-runtime-jvm-metrics.yaml @@ -1,5 +1,5 @@ groups: - - id: attributes.process.runtime.jvm.memory + - id: attributes.jvm.memory type: attribute_group brief: "Describes JVM memory metric attributes." attributes: @@ -25,41 +25,41 @@ groups: Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - - id: metric.process.runtime.jvm.memory.usage + - id: metric.jvm.memory.usage type: metric - metric_name: process.runtime.jvm.memory.usage - extends: attributes.process.runtime.jvm.memory + metric_name: jvm.memory.usage + extends: attributes.jvm.memory brief: "Measure of memory used." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.memory.committed + - id: metric.jvm.memory.committed type: metric - metric_name: process.runtime.jvm.memory.committed - extends: attributes.process.runtime.jvm.memory + metric_name: jvm.memory.committed + extends: attributes.jvm.memory brief: "Measure of memory committed." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.memory.limit + - id: metric.jvm.memory.limit type: metric - metric_name: process.runtime.jvm.memory.limit - extends: attributes.process.runtime.jvm.memory + metric_name: jvm.memory.limit + extends: attributes.jvm.memory brief: "Measure of max obtainable memory." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.memory.usage_after_last_gc + - id: metric.jvm.memory.usage_after_last_gc type: metric - metric_name: process.runtime.jvm.memory.usage_after_last_gc - extends: attributes.process.runtime.jvm.memory + metric_name: jvm.memory.usage_after_last_gc + extends: attributes.jvm.memory brief: "Measure of memory used, as measured after the most recent garbage collection event on this pool." instrument: updowncounter unit: "By" - - id: metric.process.runtime.jvm.gc.duration + - id: metric.jvm.gc.duration type: metric - metric_name: process.runtime.jvm.gc.duration + metric_name: jvm.gc.duration brief: "Duration of JVM garbage collection actions." instrument: histogram unit: "s" @@ -81,9 +81,9 @@ groups: Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - id: metric.process.runtime.jvm.threads.count + - id: metric.jvm.threads.count type: metric - metric_name: process.runtime.jvm.threads.count + metric_name: jvm.threads.count brief: "Number of executing platform threads." instrument: updowncounter unit: "{thread}" @@ -93,37 +93,37 @@ groups: type: boolean requirement_level: recommended - - id: metric.process.runtime.jvm.classes.loaded + - id: metric.jvm.classes.loaded type: metric - metric_name: process.runtime.jvm.classes.loaded + metric_name: jvm.classes.loaded brief: "Number of classes loaded since JVM start." instrument: counter unit: "{class}" - - id: metric.process.runtime.jvm.classes.unloaded + - id: metric.jvm.classes.unloaded type: metric - metric_name: process.runtime.jvm.classes.unloaded + metric_name: jvm.classes.unloaded brief: "Number of classes unloaded since JVM start." instrument: counter unit: "{class}" - - id: metric.process.runtime.jvm.classes.current_loaded + - id: metric.jvm.classes.current_loaded type: metric - metric_name: process.runtime.jvm.classes.current_loaded + metric_name: jvm.classes.current_loaded brief: "Number of classes currently loaded." instrument: updowncounter unit: "{class}" - - id: metric.process.runtime.jvm.cpu.time + - id: metric.jvm.cpu.time type: metric - metric_name: process.runtime.jvm.cpu.time + metric_name: jvm.cpu.time brief: "CPU time used by the process as reported by the JVM." instrument: counter unit: "s" - - id: metric.process.runtime.jvm.cpu.recent_utilization + - id: metric.jvm.cpu.recent_utilization type: metric - metric_name: process.runtime.jvm.cpu.recent_utilization + metric_name: jvm.cpu.recent_utilization brief: "Recent CPU utilization for the process as reported by the JVM." note: > The value range is [0.0,1.0]. diff --git a/schema-next.yaml b/schema-next.yaml index 14e82faac1..612200a0bc 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -8,6 +8,25 @@ versions: - rename_metrics: http.client.duration: http.client.request.duration http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + process.runtime.jvm.threads.count: jvm.threads.count + process.runtime.jvm.classes.loaded: jvm.classes.loaded + process.runtime.jvm.classes.unloaded: jvm.classes.unloaded + process.runtime.jvm.classes.current_loaded: jvm.classes.current_loaded + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + process.runtime.jvm.buffer.usage: jvm.buffer.usage + process.runtime.jvm.buffer.limit: jvm.buffer.limit + process.runtime.jvm.buffer.count: jvm.buffer.count 1.21.0: spans: changes: From 92ad6188573f0ae61351187615d676330096f80f Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Thu, 6 Jul 2023 04:48:13 +0000 Subject: [PATCH 41/44] Fix: fix TOC Signed-off-by: Raphael Silva --- docs/faas/aws-lambda.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 4a673a6cbe..745b21a33f 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -15,7 +15,11 @@ use cases. - [All triggers](#all-triggers) * [Determining the remote parent span context](#determining-the-remote-parent-span-context) +<<<<<<< HEAD + [Composite EventToCarrier](#composite-eventtocarrier) +======= + * [Composite EventToCarrier](#composite-eventtocarrier) +>>>>>>> e2d4572 (Fix: fix TOC) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) From 1d3b5ca6c99945d20b3d5fb684b79286ad0aa2b2 Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Thu, 6 Jul 2023 04:56:54 +0000 Subject: [PATCH 42/44] Fix: fix toc Signed-off-by: Raphael Silva --- docs/faas/aws-lambda.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 745b21a33f..4a673a6cbe 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -15,11 +15,7 @@ use cases. - [All triggers](#all-triggers) * [Determining the remote parent span context](#determining-the-remote-parent-span-context) -<<<<<<< HEAD + [Composite EventToCarrier](#composite-eventtocarrier) -======= - * [Composite EventToCarrier](#composite-eventtocarrier) ->>>>>>> e2d4572 (Fix: fix TOC) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) From 58c722c0950e036d15a724336bfc35a36c59e376 Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Mon, 14 Aug 2023 06:27:15 +0000 Subject: [PATCH 43/44] Update EvenToCarrier based on feedback * Clarify that users can provider their own EventToCarrier * Dont define the list of implementations * Remove the composite EventToCarrier --- docs/faas/aws-lambda.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 4a673a6cbe..f1b6709500 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -15,7 +15,7 @@ use cases. - [All triggers](#all-triggers) * [Determining the remote parent span context](#determining-the-remote-parent-span-context) - + [Composite EventToCarrier](#composite-eventtocarrier) + + [EventToCarrier in auto-instrumentation](#eventtocarrier-in-auto-instrumentation) - [API Gateway](#api-gateway) - [SQS](#sqs) * [SQS Event](#sqs-event) @@ -57,29 +57,29 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a ### Determining the remote parent span context -Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including any propagated context, etc.) as part of the invocation event. If using AWS X-Ray tracing then the trace context is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. A single lambda function can be triggered from multiple sources, however spans can only have a single parent. +Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including any propagated context, etc.) as part of the invocation event. If using AWS X-Ray tracing then the trace context is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. -To determine the parent span context, the lambda instrumentation SHOULD use a `EventToCarrier`. `EventToCarrier` defines how the instrumentation should prepare a `Carrier` to be used by subsequent `TextMapPropagators`. +To determine the parent span context, the lambda instrumentation SHOULD use a `EventToCarrier`. `EventToCarrier` defines how the lambda instrumentation should prepare a `Carrier` to be used by subsequent `TextMapPropagators`. -The `EventToCarrier` MUST implement the `Convert` operation to convert a lammbda `Event` into a `Carrier`. +The `EventToCarrier` MUST implement the `Convert` operation to convert a lambda `Event` into a `Carrier`. -The `Convert` operation MUST have the following parameters: - `Carrier` - the carrier that will be populated from the `Event` +The `Convert` operation MUST return a `Carrier` and MUST have the following parameters: `Event` - the lambda event. -#### Composite EventToCarrier +The `EventToCarrier` used in the lambda instrumentation SHOULD be provided as a parameter during the initialization of this +instrumentation. This parameter MAY be provided by users that provide a implementation for the `EventToCarrier`. -Implementations MUST provide a facility to group multiple `EventToCarrier`s. A composite `EventToCarrier` can be built from a list of `EventToCarrier`s. The resulting composite `EventToCarrier` will invoke the `Convert` operation of each individual `EventToCarrier` in the order they were specified, sequentially updating the carrier. +Lambda instrumentation MUST provide a default `EventToCarrier`, the `HttpEventToCarrier`, which populates the `Carrier` with the content of the http headers used to invoke the lambda function. -The list of `EventToCarrier`s passed to the composite `EventToCarrier` MUST be configured using the `OTEL_AWS_LAMBDA_EVENT_TO_CARRIERS`, as a comma separated list of values. +If no `EventToCarrier` is provided during the initialization of the lambda instrumentation, the `HttpEventToCarrier` MUST be used. -Valid values to configure the composite `EventToCarrier` are: +**NOTE**: When instrumenting a Java AWS Lambda with an `EventToCarrier` that extracts the event from the lambda environment, this `EventToCarrier` SHOULD first try to parse the `X-Amzn-Trace-Id` out of the system property `com.amazonaws.xray.traceHeader` before checking and attempting to parse the environment variable `_X_AMZN_TRACE_ID`. -* `lambda_runtime` - populates the `Carrier` with a key `X-Amzn-Trace-Id` from the value of the `_X_AMZN_TRACE_ID` environment variable. (see note below) -* `http_headers` = populates the `Carrier` with the content of the http headers. -* `sqs` - populate the carrier with the content of the `AWSTraceHeader` system attribute of the message. +#### EventToCarrier in auto-instrumentation -**NOTE**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse the `X-Amzn-Trace-Id` out of the system property `com.amazonaws.xray.traceHeader` before checking and attempting to parse the environment variable `_X_AMZN_TRACE_ID`. +In languages that support auto-instrumentation, the `EventToCarrier` used in the lambda instrumentation MAY be configured using the environment variable `OTEL_AWS_LAMBDA_EVENT_TO_CARRIER`. This environment variable MUST be set to the name of the `EventToCarrier` that will be used. + +The `HttpEventToCarrier` has name `http`. ## API Gateway From 94a3bf535de6a8d73ea25dd56f4980a5c94e2e4f Mon Sep 17 00:00:00 2001 From: Raphael Silva Date: Mon, 11 Sep 2023 21:24:27 +0000 Subject: [PATCH 44/44] Update to simplify language --- docs/faas/aws-lambda.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index f1b6709500..c3895e534e 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -59,9 +59,9 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including any propagated context, etc.) as part of the invocation event. If using AWS X-Ray tracing then the trace context is instead stored in the Lambda environment. It is also possible that both options are populated at the same time, with different values. Finally it is also possible to propagate tracing information in a SQS message using the system attribute of the message `AWSTraceHeader`. -To determine the parent span context, the lambda instrumentation SHOULD use a `EventToCarrier`. `EventToCarrier` defines how the lambda instrumentation should prepare a `Carrier` to be used by subsequent `TextMapPropagators`. +The lambda instrumentation MUST use a `EventToCarrier` to prepare a `Carrier` to be used by subsequent `TextMapPropagators`. -The `EventToCarrier` MUST implement the `Convert` operation to convert a lambda `Event` into a `Carrier`. +A `EventToCarrier` MUST implement the `Convert` operation to convert a lambda `Event` into a `Carrier`. The `Convert` operation MUST return a `Carrier` and MUST have the following parameters: `Event` - the lambda event. @@ -69,7 +69,7 @@ The `Convert` operation MUST return a `Carrier` and MUST have the following para The `EventToCarrier` used in the lambda instrumentation SHOULD be provided as a parameter during the initialization of this instrumentation. This parameter MAY be provided by users that provide a implementation for the `EventToCarrier`. -Lambda instrumentation MUST provide a default `EventToCarrier`, the `HttpEventToCarrier`, which populates the `Carrier` with the content of the http headers used to invoke the lambda function. +Lambda instrumentation MUST provide a default `EventToCarrier`, the `HttpEventToCarrier`, which populates the `Carrier` with the content of the http headers used to invoke the lambda function, when that is available. If no `EventToCarrier` is provided during the initialization of the lambda instrumentation, the `HttpEventToCarrier` MUST be used. @@ -79,7 +79,7 @@ If no `EventToCarrier` is provided during the initialization of the lambda instr In languages that support auto-instrumentation, the `EventToCarrier` used in the lambda instrumentation MAY be configured using the environment variable `OTEL_AWS_LAMBDA_EVENT_TO_CARRIER`. This environment variable MUST be set to the name of the `EventToCarrier` that will be used. -The `HttpEventToCarrier` has name `http`. +The `HttpEventToCarrier` has name `http-headers`. ## API Gateway