You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/en/docs/collector/building/_index.md
+6-2Lines changed: 6 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,10 @@ description: Instructions on how to build your own Collector components
4
4
weight: 90
5
5
---
6
6
7
-
You can configure the OpenTelemetry Collector with components from the [community](https://opentelemetry.io/docs/collector/components/) and [broader ecosystem](https://opentelemetry.io/ecosystem/registry/), and you can also develop and build on your own custom components. This section describes how to build some of those components. For additional
8
-
details, see the documentation in the
7
+
You can configure the OpenTelemetry Collector with components from the
8
+
[community](https://opentelemetry.io/docs/collector/components/) and
9
+
[broader ecosystem](https://opentelemetry.io/ecosystem/registry/), and you can
10
+
also develop and build on your own custom components. This section describes how
11
+
to build some of those components. For additional details, see the documentation
for the actual semantics of each type and function.
22
22
@@ -26,16 +26,23 @@ room at the [CNCF Slack workspace](https://slack.cncf.io).
26
26
27
27
## Architecture
28
28
29
-
[Authenticators] in OpenTelemetry are just like any other extension, but they also have to implement one or more specific interfaces that define how authentication is performed (for example, authenticating HTTP or gRPC requests). Use [server authenticators][sa]
30
-
with receivers to intercept HTTP and gRPC requests. Use client
31
-
authenticators with exporters to add authentication data to HTTP
32
-
and gRPC requests. Authenticators can also implement both
33
-
interfaces at the same time, allowing a single instance of the extension to
34
-
handle both incoming and outgoing requests. Users of your authenticator might prefer having
35
-
different authenticators for incoming and outgoing requests. Keep the design flexible so users can enable the component only on the server side, or only on the client side, or both if they choose.
29
+
[Authenticators] in OpenTelemetry are just like any other extension, but they
30
+
also have to implement one or more specific interfaces that define how
31
+
authentication is performed (for example, authenticating HTTP or gRPC requests).
32
+
Use [server authenticators][sa] with receivers to intercept HTTP and gRPC
33
+
requests. Use client authenticators with exporters to add authentication data to
34
+
HTTP and gRPC requests. Authenticators can also implement both interfaces at the
35
+
same time, allowing a single instance of the extension to handle both incoming
36
+
and outgoing requests. Users of your authenticator might prefer having different
37
+
authenticators for incoming and outgoing requests. Keep the design flexible so
38
+
users can enable the component only on the server side, or only on the client
39
+
side, or both if they choose.
36
40
37
41
Once an authenticator extension is available in a Collector distribution, you
38
-
can reference it in the configuration file the same as other extensions. However, an authenticator is effective only when it's referenced by a consuming component. The following configuration shows a receiver named `otlp/auth` using the `oidc` authenticator extension:
42
+
can reference it in the configuration file the same as other extensions.
43
+
However, an authenticator is effective only when it's referenced by a consuming
44
+
component. The following configuration shows a receiver named `otlp/auth` using
45
+
the `oidc` authenticator extension:
39
46
40
47
```yaml
41
48
extensions:
@@ -118,23 +125,31 @@ service:
118
125
119
126
### Server authenticators
120
127
121
-
A [server authenticator][sa] is an extension with an `Authenticate`
122
-
function. This function is called whenever a request comes in, and it checks the request’s headers to authenticate the request. If the authenticator decides the request is valid, it returns a `nil` error. If the request isn’t valid, it returns an error explaining why.
128
+
A [server authenticator][sa] is an extension with an `Authenticate` function.
129
+
This function is called whenever a request comes in, and it checks the request’s
130
+
headers to authenticate the request. If the authenticator decides the request is
131
+
valid, it returns a `nil` error. If the request isn’t valid, it returns an error
132
+
explaining why.
123
133
124
-
Because it’s an extension, the authenticator should set up the resources it needs (like keys, clients, or caches) at
134
+
Because it’s an extension, the authenticator should set up the resources it
The `Authenticate` function runs for every incoming request, and the pipeline can’t move forward until
129
-
this function finishes. Because of that, your authenticator must avoid slow or unnecessary blocking work. If the `context` sets a deadline, make sure your code follows it so the pipeline isn't delayed or left hanging.
139
+
The `Authenticate` function runs for every incoming request, and the pipeline
140
+
can’t move forward until this function finishes. Because of that, your
141
+
authenticator must avoid slow or unnecessary blocking work. If the `context`
142
+
sets a deadline, make sure your code follows it so the pipeline isn't delayed or
143
+
left hanging.
130
144
131
-
You should also add good observability to your authenticator, especially metrics and traces. This helps users set up alerts if errors start increasing and makes it easier for them to troubleshoot authentication problems.
145
+
You should also add good observability to your authenticator, especially metrics
146
+
and traces. This helps users set up alerts if errors start increasing and makes
147
+
it easier for them to troubleshoot authentication problems.
132
148
133
149
### Client authenticators
134
150
135
-
136
-
[Client authenticators] are
137
-
extensions with extra functions that implement one or more of the defined interfaces. Each authenticator receives an object that
151
+
[Client authenticators] are extensions with extra functions that implement one
152
+
or more of the defined interfaces. Each authenticator receives an object that
138
153
allows it to inject authentication data. For instance, the HTTP client
139
154
authenticator provides an
140
155
[`http.RoundTripper`](https://pkg.go.dev/net/http#RoundTripper), while the gRPC
@@ -145,10 +160,11 @@ client authenticator can produce a
145
160
146
161
Custom authenticators must be part of the same binary as the Collector itself.
147
162
When building your own authenticator, you have two options:
148
-
- You can build a custom Collector
149
-
distribution using
150
-
the [OpenTelemetry Collector Builder][builder]
151
-
- You can provide a way, such as publishing a Go module, for users to add your extension to their own distributions.
163
+
164
+
- You can build a custom Collector distribution using the [OpenTelemetry
165
+
Collector Builder][builder]
166
+
- You can provide a way, such as publishing a Go module, for users to add your
> Traces that track the progression of a single request, known as a trace, as it is
15
-
> handled by services that make up an application. The request may be initiated
16
-
> by a user or an application. Distributed tracing is a form of tracing
17
-
> that traverses process, network, and security boundaries.
18
-
19
-
Although distributed traces are defined in an application-centric way, you can think of them as a timeline for _any_ request that moves through your system. Each distributed trace shows how long a request took from start to finish and breaks down the steps taken to complete it.
20
-
21
-
If your system generates tracing telemetry, you can configure your [OpenTelemetry Collector](/docs/collector/) with a trace receiver designed to receive and convert that telemetry. The receiver converts your data from its original format into the OpenTelemetry trace model so the Collector can process it.
0 commit comments