diff --git a/README.md b/README.md index cc0268da227..d5ddc50485f 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,11 @@ The OpenTelemetry specification describes the cross-language requirements and ex - API Specification - [DistributedContext](specification/api-distributedcontext.md) - [Propagators](specification/api-propagators.md) - - [Resources](specification/api-resources.md) - [Tracing](specification/api-tracing.md) - [Sampling](specification/api-sampling.md) - [Metrics](specification/api-metrics.md) +- SDK Specification + - [Resource](specification/sdk-resource.md) - Data Specification - [Semantic Conventions](specification/data-semantic-conventions.md) - [Protocol](specification/protocol.md) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index bd3c5d8017e..7da3e7c2530 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -131,11 +131,6 @@ convenience methods to manage a `Span`'s lifetime and the scope in which a time) but stil active. A `Span` may be active on one thread after it has been made inactive on another. -The `Tracer` MUST support recording `Span`s that were created _out of band_, -i.e. not by the tracer itself. For this reason, implementations MUST NOT -require that a `Span`'s start and end timestamps match the wall time when it is -created, made active, or finished. - The implementation MUST provide no-op binary and text `Propagator`s, which the `Tracer` SHOULD use by default if other propagators are not configured. SDKs SHOULD use the W3C HTTP Trace Context as the default text format. For more diff --git a/specification/library-layout.md b/specification/library-layout.md index 69ce699bdd0..e990ddfbb42 100644 --- a/specification/library-layout.md +++ b/specification/library-layout.md @@ -1,33 +1,45 @@ # OpenTelemetry Project Package Layout -This documentation serves to document the "look and feel" of a basic layout for OpenTelemetry projects. This package layout is intentionally generic and it doesn't try to impose a language specific package structure. +This documentation serves to document the "look and feel" of a basic layout for OpenTelemetry +projects. This package layout is intentionally generic and it doesn't try to impose a language +specific package structure. ## API Package Here is a proposed generic package structure for OpenTelemetry API package. +A typical top-level directory layout: +``` +api + ├── context + │ └── propagation + ├── metrics + ├── trace + │ └── propagation + ├── distributedcontext + │ └── propagation + ├── internal + └── logs +``` +> Use of lowercase, CamelCase or Snake Case (stylized as snake_case) names depends on the language. + ### `/context` This directory describes the API that provides in-process context propagation. -### `/metrics` +### [/metrics](api-metrics.md) This directory describes the Metrics API that can be used to record application metrics. -### `/resources` - -This API for resource information population. - -The resource directory primarily defines a type [Resource](overview.md#resources) that captures information about the entity for which stats or traces are recorded. For example, metrics exposed by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name. - -### `/distributedcontext` +### [/distributedcontext](api-distributedcontext.md) -This directory describes the DistributedContext API that can be used to manage context propagation and metrics-related labeling. +This directory describes the DistributedContext API that can be used to manage context propagation +and metrics-related labeling. This API consists of a few main classes: - `Entry` is used to label anything that is associated with a specific operation, such as an HTTP request. - An `Entry` consists of `EntryMetadata`, `EntryKey`, and `EntryValue`. -### `/trace` +### [/trace](api-tracing.md) This API consist of a few main classes: @@ -41,18 +53,46 @@ Private application and library code. ### `/logs` (_In the future_) > TODO: logs operations +## SDK Package +Here is a proposed generic package structure for OpenTelemetry SDK package. A typical top-level directory layout: ``` -api +sdk ├── context - │ └── propagation ├── metrics - ├── resources + ├── resource ├── trace ├── distributedcontext - │ └── propagation ├── internal └── logs ``` > Use of lowercase, CamelCase or Snake Case (stylized as snake_case) names depends on the language. + +### `/sdk/context` + +This directory describes the SDK implementation for api/context. + +### `/sdk/metrics` + +This directory describes the SDK implementation for api/metrics. + +### [/sdk/resource](sdk-resource.md) + +The resource directory primarily defines a type [Resource](overview.md#resources) that captures +information about the entity for which stats or traces are recorded. For example, metrics exposed +by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, +and container name. + +### `/sdk/distributedcontext` + + +### [/sdk/trace](sdk-tracing.md) + +This directory describes the SDK implementation for api/metrics. + +### `/sdk/internal` (_Optional_) +Private application and library code. + +### `/sdk/logs` (_In the future_) +> TODO: logs operations diff --git a/specification/api-resources.md b/specification/sdk-resource.md similarity index 67% rename from specification/api-resources.md rename to specification/sdk-resource.md index 3e03eb42ad0..b7681fc40bc 100644 --- a/specification/api-resources.md +++ b/specification/sdk-resource.md @@ -1,4 +1,4 @@ -# Resources API +# Resource SDK A [Resource](overview.md#resources) represents the entity producing telemetry. The primary purpose of resources as a first-class concept in the API is @@ -8,29 +8,24 @@ with closed source environments. API MUST allow for creation of `Resources` and for associating them with telemetry. When used with distributed tracing, a resource can be associated with the -[Tracer](api-tracing.md#tracer). When associated with `Tracer`, all `Span`s -produced by this `Tracer` will automatically be associated with this `Resource`. -When associated with a `Span` explicitly for out-of-band spans - -`Resource` that is set on `Tracer` MUST be ignored. Note, that association of -`Tracer` with the `Resource` will be done in SDK, not as API call. +[TracerSdk](sdk-tracing.md#tracer-sdk). When associated with `TracerSdk`, all +`Span`s produced by the `Tracer`, that is implemented by this `TracerSdk`, will +automatically be associated with this `Resource`. -**TODO**: explain how resource is associated with metrics. - -## Resources SDK - -TODO: notes how Resources API is extended when using `SDK`. https://github.com/open-telemetry/opentelemetry-specification/issues/61 +When used with metrics, a resource can be associated with the +[MeterSdk](sdk-metrics.md#meter-sdk). When associated with `MeterSdk`, all +`Metrics` produced by this `Meter`, that is implemented by this `MeterSdk`, will +automatically be associated with this `Resource`. ## Resource creation -The API interface must support two ways to instantiate new resources. Those -are: +The API interface must support two ways to instantiate new resources. Those are: ### Create -The interface MUST provide a way to create a new resource, from a collection -of labels. Examples include a factory method or a constructor for -a resource object. A factory method is recommended to enable support for -cached objects. +The interface MUST provide a way to create a new resource, from a collection of +labels. Examples include a factory method or a constructor for a resource +object. A factory method is recommended to enable support for cached objects. Required parameters: @@ -38,17 +33,17 @@ Required parameters: ### Merge -The interface MUST provide a way for a primary resource to merge with a -secondary resource, resulting in the creation of a brand new resource. The +The interface MUST provide a way for a primary resource to merge with a +secondary resource, resulting in the creation of a brand new resource. The original resources should be unmodified. This is utilized for merging of resources whose labels come from different -sources, such as environment variables, or metadata extracted from the host or +sources, such as environment variables, or metadata extracted from the host or container. -Already set labels MUST NOT be overwritten unless they are the empty string. +Already set labels MUST NOT be overwritten unless they are the empty string. -Label key namespacing SHOULD be used to prevent collisions across different +Label key namespacing SHOULD be used to prevent collisions across different resource detection steps. Required parameters: @@ -58,7 +53,7 @@ Required parameters: ### The empty resource -It is recommended, but not required, to provide a way to quickly create an empty +It is recommended, but not required, to provide a way to quickly create an empty resource. Note that the OpenTelemetry project documents certain ["standard @@ -71,12 +66,12 @@ In addition to resource creation, the following operations should be provided: ### Retrieve labels The API should provide a way to retrieve a read only collection of labels -associated with a resource. The labels should consist of the name and values, +associated with a resource. The labels should consist of the name and values, both of which should be strings. There is no need to guarantee the order of the labels. -The most common operation when retrieving labels is to enumerate over them. -As such, it is recommended to optimize the resulting collection for fast -enumeration over other considerations such as a way to quickly retrieve a -value for a label with a specific key. +The most common operation when retrieving labels is to enumerate over them. As +such, it is recommended to optimize the resulting collection for fast +enumeration over other considerations such as a way to quickly retrieve a value +for a label with a specific key.