diff --git a/specification/package-layout.md b/specification/package-layout.md new file mode 100644 index 00000000000..c37a1574bdd --- /dev/null +++ b/specification/package-layout.md @@ -0,0 +1,61 @@ +# 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. + +## API Package +Here is a proposed generic package structure for OpenTelemetry API package. + +### `/context` + +This directory describes the API that provides in-process context propagation. + +### `/metrics` + +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](../terminology.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` + +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` + +This API consist of a few main classes: + +- `Tracer` is used for all operations. See [Tracer](./tracing-api.md#tracer) section. +- `Span` is a mutable object storing information about the current operation + execution. See [Span](./tracing-api.md#span) section. +- `SpanData` is an immutable object that is used to report out-of-band completed + spans. See [SpanData](./tracing-api.md#spandata) section. + +### `/internal` (_Optional_) +Private application and library code. + +### `/logs` (_In the future_) +> TODO: logs operations + + +A typical top-level directory layout: +``` +api + ├── context + │ └── propagation + ├── metrics + ├── resources + ├── trace + │ └── samplers # is used to make decisions on `Span` sampling. + ├── distributedcontext + │ └── propagation + ├── internal + └── logs +``` +> Use lowercase or CamelCase or Snake Case (stylized as snake_case) names depends on the language.