Skip to content

Commit 5efc10e

Browse files
committed
[docs] add guidance around what a collector/distro is
Fixes open-telemetry#8555 Signed-off-by: Alex Boten <[email protected]>
1 parent c2af75d commit 5efc10e

File tree

1 file changed

+60
-0
lines changed

1 file changed

+60
-0
lines changed

docs/README.md

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

0 commit comments

Comments
 (0)