Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move resource to SDK. #254

Merged
merged 10 commits into from
Sep 27, 2019
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
5 changes: 0 additions & 5 deletions specification/api-tracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
70 changes: 55 additions & 15 deletions specification/library-layout.md
Original file line number Diff line number Diff line change
@@ -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
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
│ └── 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:

Expand All @@ -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
51 changes: 23 additions & 28 deletions specification/api-resources.md → specification/sdk-resource.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -8,47 +8,42 @@ 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:

- a collection of name/value labels, where name and value are both strings.

### 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:
Expand All @@ -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
Expand All @@ -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.