diff --git a/experimental/metrics/config-service.md b/experimental/metrics/config-service.md index 311d9a49c83..9fdf76685d5 100644 --- a/experimental/metrics/config-service.md +++ b/experimental/metrics/config-service.md @@ -50,7 +50,7 @@ A request consists of two fields: `resource` and an optional `last_known_fingerprint`. `resource` is an OpenTelemetry -[Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#resources) +[Resource](../../specification/overview.md#resources) that describes a source of telemetry data. All requests SHOULD have a nonempty `resource` field. diff --git a/experimental/trace/zpages.md b/experimental/trace/zpages.md index 69f7cdf828f..c2d62d2eac4 100644 --- a/experimental/trace/zpages.md +++ b/experimental/trace/zpages.md @@ -32,7 +32,7 @@ zPages are uniquely useful in a couple of different ways. One is that they're mo ### Tracez -Tracez shows information on tracing, including aggregation counts for latency, running, and errors for spans grouped by name. Latency spans are spans that complete successfully without errors, and are bucketed according to their end time. Running spans are incomplete spans, which should become latency or error spans at some point. Error spans are ones that complete with an error, which is encoded with a [non-Ok status](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#status). In addition to these counts, Tracez also keeps a set number of samples for each of these error, running, and latency (including within each duration bucket) buckets within each span name to allow users to look closer at span fields. This is particularly useful compared to external exporters that would otherwise likely sample them out. +Tracez shows information on tracing, including aggregation counts for latency, running, and errors for spans grouped by name. Latency spans are spans that complete successfully without errors, and are bucketed according to their end time. Running spans are incomplete spans, which should become latency or error spans at some point. Error spans are ones that complete with an error, which is encoded with a [non-Ok status](../../specification/trace/api.md#set-status). In addition to these counts, Tracez also keeps a set number of samples for each of these error, running, and latency (including within each duration bucket) buckets within each span name to allow users to look closer at span fields. This is particularly useful compared to external exporters that would otherwise likely sample them out. This zPage is also useful for debugging latency issues (slow parts of applications), deadlocks and instrumentation problems (running spans that don't end), and errors (where errors happen and what types). They're also good for spotting patterns by showing which latency speeds are typical for operations with a given span name. @@ -54,7 +54,7 @@ Statsz is focused on metrics, as it displays metrics and measures for exported v ### Tracez Details -For OpenTelemetry, a custom [span processor](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-processor) SHOULD be made to interface with the [Tracer API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracer) to collect spans. This span processor collects references to running spans and exports completed spans to its own memory or to an aggregator that can aggregate information from multiple span processors. +For OpenTelemetry, a custom [span processor](../../specification/trace/sdk.md#span-processor) SHOULD be made to interface with the [Tracer API](../../specification/trace/api.md#tracer) to collect spans. This span processor collects references to running spans and exports completed spans to its own memory or to an aggregator that can aggregate information from multiple span processors. There SHOULD be a `data aggregator` that tracks running, error, and latency buckets counts for spans grouped by their respective name. The aggregator MUST also hold some sampled spans to provide users with more information. To prevent memory overload, only some spans MUST be sampled for each bucket for each span name; for example, if that sampled span max number is set to 5, then only up to 55 pieces of span data can be kept for each span name in the aggregator (sampled_max * number of buckets = 5 * [running + error + 9 latency buckets] = 5 * 11 = 55). Aggregation work is recommended to do periodically in batches. diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 4fe82168088..cdcc11f5293 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -14,7 +14,8 @@ groups: type: string required: always brief: > - The unique ID of the function being executed. + The unique ID of the function + being executed. note: > For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) @@ -26,7 +27,7 @@ groups: type: string brief: > The version string of the function being executed as defined in - [Version Attributes](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#version-attributes). + [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). examples: ['2.0.0'] - id: instance type: string diff --git a/semantic_conventions/resource/host.yaml b/semantic_conventions/resource/host.yaml index 386ab17f809..99264ca9d3d 100644 --- a/semantic_conventions/resource/host.yaml +++ b/semantic_conventions/resource/host.yaml @@ -35,5 +35,5 @@ groups: type: string brief: > The version string of the VM image as defined in - [Version Attributes](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#version-attributes). + [Version Attributes](README.md#version-attributes). examples: ['0.1'] diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 92cb96a99dc..6cac1d2769e 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -11,24 +11,24 @@ status of the feature is not known. |Feature |Go |Java|JS |Python|Ruby|Erlang|PHP|Rust|C++|.Net| |----------------------------------------------|---|----|---|------|----|------|---|----|---|----| -|[TracerProvider](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracerprovider-operations)| +|[TracerProvider](specification/trace/api.md#tracerprovider-operations)| |Create TracerProvider | + | + | + | + | + | + | + | + | + | + | |Get a Tracer | + | + | + | + | + | + | + | + | + | + | |Safe for concurrent calls | + | + | + | + | + | + | + | + | + | + | |Shutdown (SDK only required) | | + | + | + | + | | | + | | | -|[Tracing Context Utilities](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracing-context-utilities)| +|[Trace / Context interaction](specification/trace/api.md#context-interaction)| |Get active Span | | + | + | + | + | | | + | | | |Set active Span | | + | + | + | + | | | + | | | -|[Tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracer-operations)| +|[Tracer](specification/trace/api.md#tracer-operations)| |Create a new Span | + | + | + | + | + | + | + | + | + | + | |Get active Span | + | + | + | + | + | + | + | + | + | + | |Mark Span active | + | + | + | + | + | + | + | + | - | - | |Safe for concurrent calls | + | + | + | + | + | + | + | + | + | + | -|[SpanContext](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spancontext)| +|[SpanContext](specification/trace/api.md#spancontext)| |IsValid | + | + | + | + | + | + | + | + | + | + | |IsRemote | - | + | + | + | + | + | + | + | + | + | |Conforms to the W3C TraceContext spec | + | + | + | + | + | + | | + | + | + | -|[Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span)| +|[Span](specification/trace/api.md#span)| |Create root span | + | + | + | + | + | + | + | + | + | + | |Create with default parent (active span) | + | + | + | + | + | + | + | + | + | + | |Create with parent from Context | + | + | + | + | + | + | + | + | + | + | @@ -45,7 +45,7 @@ status of the feature is not known. |events collection size limit | | + | + | + | + | | | + | | | |attribute collection size limit | | + | + | + | + | | | + | | | |links collection size limit | | + | + | + | + | | | + | | | -|[Span attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#set-attributes)| +|[Span attributes](specification/trace/api.md#set-attributes)| |SetAttribute | + | + | + | + | + | + | + | + | + | + | |Set order preserved | + | - | + | + | + | + | + | + | + | + | |String type | + | + | + | + | + | + | + | + | + | + | @@ -55,17 +55,17 @@ status of the feature is not known. |Array of primitives (homogeneous) | + | + | + | + | + | - | + | + | + | + | |`null` values documented as invalid/undefined | | + | | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1304) | | | | | | | |Unicode support for keys and string values | + | + | + | + | + | + | + | + | + | + | -|[Span linking](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#add-links)| +|[Span linking](specification/trace/api.md#specifying-links)| |AddLink | + | + | + | + | + | + | + | + | - | + | |Safe for concurrent calls | + | + | + | + | + | + | + | + | - | + | -|[Span events](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#add-events)| +|[Span events](specification/trace/api.md#add-events)| |AddEvent | + | + | + | + | + | + | + | + | - | + | |Add order preserved | + | + | + | + | + | + | + | + | - | + | |Safe for concurrent calls | + | + | + | + | + | + | + | + | - | + | -|[Span exceptions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#record-exception)| +|[Span exceptions](specification/trace/api.md#record-exception)| |RecordException | - | + | + | + | + | - | | + | - | + | |RecordException with extra parameters | - | + | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1102) | - | - | | + | - | + | -|[Sampling](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampling)| +|[Sampling](specification/trace/sdk.md#sampling)| |Allow samplers to modify tracestate | | + | | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1220) | | | | + | | | |ShouldSample gets full parent Context | | + | | + | | | | | | | @@ -106,7 +106,7 @@ status of the feature is not known. |TraceContext Propagator | | + | + | + | + | | | + | | | |B3 Propagator | | + | + | + | + | | | + | | | |Jaeger Propagator | | [-](https://github.com/open-telemetry/opentelemetry-java/pull/1549) | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1103) | | | | + | | | -|[TextMapPropagator](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md#textmap-propagator)| +|[TextMapPropagator](specification/context/api-propagators.md#textmap-propagator)| |Fields | | + | [-](https://github.com/open-telemetry/opentelemetry-js/pull/1615) | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1104) | | | | + | | | |Setter argument | | + | + | + | | | | | | | |Getter argument | | + | + | + | | | | | | | @@ -135,7 +135,7 @@ status of the feature is not known. |----------------------------------------------|---|----|---|------|----|------|---|----|---|----| |Standard output (logging) | + | + | + | + | + | + | - | + | + | + | |In-memory (mock exporter) | + | + | + | + | + | + | - | - | - | - | -|[OTLP](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/protocol/otlp.md)| +|[OTLP](specification/protocol/otlp.md)| |OTLP/gRPC Exporter | + | + | + | + | | + | | + | + | + | |OTLP/HTTP binary Protobuf Exporter | - | - | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1106) | + | + | | | + | + | |OTLP/HTTP JSON Protobuf Exporter | - | - | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1003) | | - | | | | | @@ -145,7 +145,7 @@ status of the feature is not known. |Honors non-retryable responses | + | | - | + | + | - | | | | | |Honors throttling response | + | | - | + | + | - | | | | | |Multi-destination spec compliance | - | | | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1109) | | - | | | | | -|[Zipkin](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk_exporters/zipkin.md)| +|[Zipkin](specification/trace/sdk_exporters/zipkin.md)| |Zipkin V1 JSON | | | | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1173) | | - | - | - | | | |Zipkin V1 Thrift | | | | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1174) | | - | - | - | | | |Zipkin V2 JSON | + | | | + | | - | + | + | | | diff --git a/specification/common/common.md b/specification/common/common.md index 974cf518214..0352f819abf 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -82,10 +82,10 @@ Names SHOULD follow these rules: - When coming up with a new semantic convention make sure to check existing namespaces for - [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions), - [Spans](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions), + [Resources](../resource/semantic_conventions/README.md), + [Spans](../trace/semantic_conventions/README.md), and - [Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions) + [Metrics](../metrics/semantic_conventions/README.md) to see if the new name fits. - When a new namespace is necessary consider whether it should be a top-level @@ -111,10 +111,10 @@ Names SHOULD follow these rules: As an application developer when you need to record an attribute or a label first consult existing semantic conventions for -[Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions), -[Spans](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions), +[Resources](../resource/semantic_conventions/README.md), +[Spans](../trace/semantic_conventions/README.md), and -[Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions). +[Metrics](../metrics/semantic_conventions/README.md). If an appropriate name does not exists you will need to come up with a new name. To do that consider a few options: diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index ce807f89c3f..816b277e4b4 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -378,7 +378,7 @@ occurrence of the event coming from the same source. This field is optional. Type: key/value pair list. Description: Describes the source of the log, aka -[resource](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#resources). +[resource](../overview.md#resources). "key" of each pair is a `string` and "value" is of `any` type. Multiple occurrences of events coming from the same event source can happen across time and they all have the same value of `Resource`. Can contain for example @@ -387,7 +387,7 @@ infrastructure where the application runs. Data formats that represent this data model may be designed in a manner that allows the `Resource` field to be recorded only once per batch of log records that come from the same source. SHOULD follow OpenTelemetry -[semantic conventions for Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions). +[semantic conventions for Resources](../resource/semantic_conventions/README.md). This field is optional. ### Field: `Attributes` @@ -400,7 +400,7 @@ field, which is fixed for a particular source, `Attributes` can vary for each occurrence of the event coming from the same source. Can contain information about the request context (other than TraceId/SpanId). SHOULD follow OpenTelemetry -[semantic conventions for Attributes](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions). +[semantic conventions for Attributes](../trace/semantic_conventions/README.md). This field is optional. ## Example Log Records @@ -1215,7 +1215,7 @@ It may contain what hostname returns on Unix systems, the fully qualified, or a \* Not yet formalized into ECS. \*\* A resource that doesn’t exist in the -[OpenTelemetry resource semantic convention](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions). +[OpenTelemetry resource semantic convention](../resource/semantic_conventions/README.md). This is a selection of the most relevant fields. See [for the full reference](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 91a37d1db17..b65ee88a895 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -73,7 +73,7 @@ These terms are defined in the Metrics API specification: Defined in the [Resource SDK](../resource/sdk.md) specification: - **Resource**: a set of key-values with unique keys describing the process -- [**Instrumentation Library**](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/glossary.md#instrumentation-library): the name and version associated with a package of instrumentation. +- [**Instrumentation Library**](../glossary.md#instrumentation-library): the name and version associated with a package of instrumentation. These are the significant data types used in the model architecture: diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 563ed00a802..a637ee70467 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -9,7 +9,7 @@ |---|---|---|---|---| | `faas.name` | string | The name of the function being executed. | `my-function` | Yes | | `faas.id` | string | The unique ID of the function being executed. [1] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes | -| `faas.version` | string | The version string of the function being executed as defined in [Version Attributes](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#version-attributes). | `2.0.0` | No | +| `faas.version` | string | The version string of the function being executed as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `2.0.0` | No | | `faas.instance` | string | The execution environment ID as a string. | `my-function:instance-0001` | No | **[1]:** For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field. diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md index d93ead14063..af5681a336b 100644 --- a/specification/resource/semantic_conventions/host.md +++ b/specification/resource/semantic_conventions/host.md @@ -12,5 +12,5 @@ | `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | No | | `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`
`CentOS-8-x86_64-1905` | No | | `host.image.id` | string | VM image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | No | -| `host.image.version` | string | The version string of the VM image as defined in [Version Attributes](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#version-attributes). | `0.1` | No | +| `host.image.version` | string | The version string of the VM image as defined in [Version Attributes](README.md#version-attributes). | `0.1` | No | diff --git a/specification/trace/api.md b/specification/trace/api.md index dff2ab9dd7c..0d3f88ac60f 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -240,8 +240,8 @@ and MUST follow the [general error handling guidelines](../error-handling.md) (e Please note, since `SpanContext` is immutable, it is not possible to update `SpanContext` with a new `TraceState`. Such changes then make sense only right before -[`SpanContext` propagation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md) -or [telemetry data exporting](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-exporter). +[`SpanContext` propagation](../context/api-propagators.md) +or [telemetry data exporting](sdk.md#span-exporter). In both cases, `Propagators` and `SpanExporters` may create a modified `TraceState` copy before serializing it to the wire. ## Span diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md index f975cc3ed8a..3aaad32d151 100644 --- a/specification/trace/semantic_conventions/exceptions.md +++ b/specification/trace/semantic_conventions/exceptions.md @@ -98,4 +98,4 @@ 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://golang.org/pkg/runtime/debug/#Stack -[telemetry-sdk-resource]: https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#telemetry-sdk +[telemetry-sdk-resource]:../../resource/semantic_conventions/README.md#telemetry-sdk