Skip to content

Commit dc62746

Browse files
authored
[docs] add guidance around what a collector/distro is (#12435)
Fixes #8555 --------- Signed-off-by: Alex Boten <[email protected]>
1 parent 9861e0a commit dc62746

File tree

1 file changed

+62
-0
lines changed

1 file changed

+62
-0
lines changed

docs/README.md

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# OpenTelemetry Collector
2+
3+
**Status**: [Beta](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0232-maturity-of-otel.md#beta)
4+
5+
The OpenTelemetry Collector consists of the following components:
6+
7+
* A mechanism that _MUST_ be able to load and parse an [OpenTelemetry Collector configuration
8+
file](#configuration-file).
9+
* A mechanism that _MUST_ be able to include compatible
10+
[Collector components](#opentelemetry-collector-components) that
11+
the user wishes to include.
12+
13+
These combined provide users the ability to easily switch between
14+
[OpenTelemetry Collector Distributions](#opentelemetry-collector-distribution) while also ensuring that components produced by
15+
the OpenTelemetry Collector SIG are able to work with any vendor who claims
16+
support for an OpenTelemetry Collector.
17+
18+
## Configuration file
19+
20+
An OpenTelemetry Collector configuration file is defined as YAML and _MUST_ support
21+
the following [minimum structure](https://pkg.go.dev/go.opentelemetry.io/collector/otelcol#Config):
22+
23+
```yaml
24+
receivers:
25+
processors:
26+
exporters:
27+
connectors:
28+
extensions:
29+
service:
30+
telemetry:
31+
pipelines:
32+
```
33+
34+
## OpenTelemetry Collector components
35+
36+
For a library to be considered an OpenTelemetry Collector component, it _MUST_
37+
implement a [Component interface](https://pkg.go.dev/go.opentelemetry.io/collector/component#Component)
38+
defined by the OpenTelemetry Collector SIG.
39+
40+
Components require a [unique identfier](https://pkg.go.dev/go.opentelemetry.io/collector/component#ID)
41+
to be included in an OpenTelemetry Collector. In the event of a name collision,
42+
the components resulting in the collision cannot be used simultaneously in a single OpenTelemetry
43+
Collector. In order to resolve this, the clashing components must use different identifiers.
44+
45+
### Compatibility requirements
46+
47+
A component is defined as compatible with an OpenTelemetry Collector when its dependencies are
48+
source- and version-compatible with the Component interfaces of that Collector.
49+
50+
For example, a Collector derived from version tag v0.100.0 of the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) _MUST_ support all components that
51+
are version-compatible with the Golang Component API defined in the `github.com/open-telemetry/opentelemetry-collector/component` module found in that repository for that version tag.
52+
53+
## OpenTelemetry Collector Distribution
54+
55+
An OpenTelemetry Collector Distribution (Distro) is a compiled instance
56+
of an OpenTelemetry Collector with a specific set of components and features. A
57+
Distribution author _MAY_ choose to produce a distribution by utilizing tools
58+
and/or documentation supported by the OpenTelemetry project. Alternatively, a
59+
Distribution author _MUST_ provide end users with the capability for adding
60+
their own components to the Distribution's components. Note that the resulting
61+
binary from updating a Distribution to include new components
62+
is a different Distribution.

0 commit comments

Comments
 (0)