init

2026-06-25 11:46:39 +09:00
commit 06a95a6d5b
56 changed files with 10023 additions and 0 deletions
@@ -0,0 +1,123 @@
+# OpenTelemetry Overview
+
+> Source: https://raw.githubusercontent.com/open-telemetry/opentelemetry-specification/main/specification/overview.md
+> Downloaded: 2026-06-07
+
+This document provides an overview of the OpenTelemetry project and defines important fundamental terms.
+
+## OpenTelemetry Client Architecture
+
+At the highest architectural level, OpenTelemetry clients are organized into **signals**. Each signal provides a specialized form of observability. For example, tracing, metrics, and baggage are three separate signals. Signals share a common subsystem – **context propagation** – but they function independently from each other.
+
+Each signal consists of four types of packages: API, SDK, Semantic Conventions, and Contrib.
+
+### API
+
+API packages consist of the cross-cutting public interfaces used for instrumentation. Any portion of an OpenTelemetry client which is imported into third-party libraries and application code is considered part of the API.
+
+### SDK
+
+The SDK is the implementation of the API provided by the OpenTelemetry project. Within an application, the SDK is installed and managed by the application owner.
+
+### Semantic Conventions
+
+The **Semantic Conventions** define the keys and values which describe commonly observed concepts, protocols, and operations used by applications.
+
+Semantic Conventions are now located in their own repository:
+https://github.com/open-telemetry/semantic-conventions
+
+### Contrib Packages
+
+The OpenTelemetry project maintains integrations with popular OSS projects. **API Contrib** refers to packages which depend solely upon the API; **SDK Contrib** refers to packages which also depend upon the SDK.
+
+## Tracing Signal
+
+A distributed trace is a set of events, triggered as a result of a single logical operation, consolidated across various components of an application.
+
+### Traces
+
+**Traces** in OpenTelemetry are defined implicitly by their **Spans**. A **Trace** can be thought of as a directed acyclic graph (DAG) of **Spans**, where the edges between **Spans** are defined as parent/child relationship.
+
+```
+Causal relationships between Spans in a single Trace
+
+        [Span A]  (the root span)
+            |
+     +------+------+
+     |             |
+ [Span B]      [Span C]
+     |             |
+ [Span D]      +---+-------+
+               |           |
+           [Span E]    [Span F]
+```
+
+### Spans
+
+A span represents an operation within a transaction. Each **Span** encapsulates:
+
+- An operation name
+- A start and finish timestamp
+- **Attributes**: A list of key-value pairs
+- A set of zero or more **Events**
+- Parent's **Span** identifier
+- **Links** to zero or more causally-related **Spans**
+- **SpanContext** information
+
+### SpanContext
+
+Represents all the information that identifies **Span** in the **Trace**:
+
+- **TraceId** - 16 randomly generated bytes, worldwide unique
+- **SpanId** - 8 randomly generated bytes, globally unique
+- **TraceFlags** - 1 byte bitmap (includes sampling bit)
+- **Tracestate** - tracing-system specific context in key-value pairs
+
+## Metric Signal
+
+OpenTelemetry allows recording raw measurements or metrics with predefined aggregations and a set of attributes.
+
+### Instruments
+
+Instruments are used to report `Measurement`s, identified by a name, kind, description, and unit of values. Types include counters, gauges, and histograms. Instruments can be synchronous or asynchronous.
+
+## Log Signal
+
+### Data model
+
+[Log Data Model](logs/data-model.md) defines how logs and events are understood by OpenTelemetry.
+
+## Baggage Signal
+
+OpenTelemetry provides a simple mechanism for propagating name/value pairs, called `Baggage`. `Baggage` is intended for indexing observability events in one service with attributes provided by a prior service in the same transaction.
+
+## Resources
+
+`Resource` captures information about the entity for which telemetry is recorded. For example, metrics exposed by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name.
+
+## Context Propagation
+
+All of OpenTelemetry cross-cutting concerns share an underlying `Context` mechanism for storing state and accessing data across the lifespan of a distributed transaction.
+
+## Propagators
+
+OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values such as `Span`s and `Baggage`.
+
+The Propagators API currently defines one `Propagator` type:
+
+- `TextMapPropagator` injects values into and extracts values from carriers as text.
+
+## Collector
+
+The OpenTelemetry Collector is a set of components that can collect traces, metrics and other telemetry data from processes instrumented by OpenTelemetry or other monitoring/tracing libraries (Jaeger, Prometheus, etc.), do aggregation and smart sampling, and export traces and metrics to one or more monitoring/tracing backends.
+
+The OpenTelemetry Collector has two primary modes of operation: **Agent** (a daemon running locally with the application) and **Collector** (a standalone running service).
+
+## Instrumentation Libraries
+
+A library that enables OpenTelemetry observability for another library is called an **Instrumentation Library**.
+
+For instrumentation hosted in OpenTelemetry repositories, the recommendation is to prefix packages with "opentelemetry-instrumentation", followed by the instrumented library name. Examples:
+
+* opentelemetry-instrumentation-flask (Python)
+* @opentelemetry/instrumentation-grpc (JavaScript)