From 94409c6e4a78ab14763e11b974c51a8d68e184ac Mon Sep 17 00:00:00 2001 From: Mayur Kale Date: Fri, 7 Jun 2019 13:50:32 -0700 Subject: [PATCH 1/3] Add basic package layout --- specification/package-layout.md | 56 +++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 specification/package-layout.md diff --git a/specification/package-layout.md b/specification/package-layout.md new file mode 100644 index 00000000000..a9f74090b98 --- /dev/null +++ b/specification/package-layout.md @@ -0,0 +1,56 @@ +# 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 Public API package. + +### `/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 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. + +### `/log` (_In the future_) +> TODO: log operations + + +A typical top-level directory layout: +``` +api + ├── metrics + ├── resources + ├── trace + │ ├── propagation # headers that are the public API for trace propagation, using different encodings. + │ └── samplers # is used to make decisions on `Span` sampling. + ├── distributedcontext + │ └── propagation + ├── internal + └── log +``` +> Use lowercase or CamelCase or Snake Case (stylized as snake_case) depends on the language. From 6993297cbd2a89360683e17fd671f991da2b0e49 Mon Sep 17 00:00:00 2001 From: Mayur Kale Date: Fri, 7 Jun 2019 21:48:03 -0700 Subject: [PATCH 2/3] Fix review comments --- specification/package-layout.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/specification/package-layout.md b/specification/package-layout.md index a9f74090b98..68e106c0cf6 100644 --- a/specification/package-layout.md +++ b/specification/package-layout.md @@ -2,11 +2,11 @@ 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 Public API package. +Here is a proposed generic package structure for OpenTelemetry API package. ### `/metrics` -This directory describes the Metrics API that can be used to record application Metrics. +This directory describes the Metrics API that can be used to record application metrics. ### `/resources` @@ -16,7 +16,7 @@ The resource directory primarily defines a type [Resource](../terminology.md#res ### `/distributedcontext` -This directory describes the DistributedContext API that can be used to manage 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: @@ -36,8 +36,8 @@ This API consist of a few main classes: ### `/internal` (_Optional_) Private application and library code. -### `/log` (_In the future_) -> TODO: log operations +### `/logs` (_In the future_) +> TODO: logs operations A typical top-level directory layout: @@ -46,11 +46,10 @@ api ├── metrics ├── resources ├── trace - │ ├── propagation # headers that are the public API for trace propagation, using different encodings. │ └── samplers # is used to make decisions on `Span` sampling. ├── distributedcontext │ └── propagation ├── internal - └── log + └── logs ``` -> Use lowercase or CamelCase or Snake Case (stylized as snake_case) depends on the language. +> Use lowercase or CamelCase or Snake Case (stylized as snake_case) names depends on the language. From 84c835b1746d14fa18d087d789728bb5e071afad Mon Sep 17 00:00:00 2001 From: Mayur Kale Date: Mon, 10 Jun 2019 12:20:16 -0700 Subject: [PATCH 3/3] Add context package --- specification/package-layout.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/package-layout.md b/specification/package-layout.md index 68e106c0cf6..c37a1574bdd 100644 --- a/specification/package-layout.md +++ b/specification/package-layout.md @@ -4,6 +4,10 @@ This documentation serves to document the "look and feel" of a basic layout for ## 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. @@ -43,6 +47,8 @@ Private application and library code. A typical top-level directory layout: ``` api + ├── context + │ └── propagation ├── metrics ├── resources ├── trace