Skip to content

Commit 78302c6

Browse files
matt-gpmatt-gp
committed
feat(otelcol.receiver) - Github
This PR adds the opentelemetry github receiver.
1 parent 0e105fd commit 78302c6

File tree

9 files changed

+645
-73
lines changed

9 files changed

+645
-73
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Main (unreleased)
1818

1919
- Add htpasswd file based authentication for `otelcol.auth.basic` (@pkarakal)
2020

21+
- A new `otelcol.receiver.github` component which collects data from Github. (@matt-gp)
22+
2123
### Enhancements
2224

2325
- update promtail converter to use `file_match` block for `loki.source.file` instead of going through `local.file_match`. (@kalleep)

‎docs/sources/reference/compatibility/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -391,6 +391,7 @@ The following components, grouped by namespace, _consume_ OpenTelemetry `otelcol
391391
- [otelcol.receiver.file_stats](../components/otelcol/otelcol.receiver.file_stats)
392392
- [otelcol.receiver.filelog](../components/otelcol/otelcol.receiver.filelog)
393393
- [otelcol.receiver.fluentforward](../components/otelcol/otelcol.receiver.fluentforward)
394+
- [otelcol.receiver.github](../components/otelcol/otelcol.receiver.github)
394395
- [otelcol.receiver.googlecloudpubsub](../components/otelcol/otelcol.receiver.googlecloudpubsub)
395396
- [otelcol.receiver.influxdb](../components/otelcol/otelcol.receiver.influxdb)
396397
- [otelcol.receiver.jaeger](../components/otelcol/otelcol.receiver.jaeger)

‎docs/sources/reference/components/otelcol/otelcol.receiver.github.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
---
2+
canonical: https://grafana.com/docs/alloy/latest/reference/components/otelcol/otelcol.receiver.github/
3+
description: Learn about otelcol.receiver.github
4+
labels:
5+
stage: experimental
6+
products:
7+
- oss
8+
title: otelcol.receiver.github
9+
---
10+
11+
# `otelcol.receiver.github`
12+
13+
{{< docs/shared lookup="stability/experimental.md" source="alloy" version="<ALLOY_VERSION>" >}}
14+
15+
`otelcol.receiver.github` collects metrics about repositories, pull requests, branches, and contributors.
16+
You can also configure it to receive webhook events from GitHub Actions and convert these into traces.
17+
18+
You can specify multiple `otelcol.receiver.github` components by giving them different labels.
19+
20+
Ensure you have the following:
21+
22+
- A GitHub Personal Access Token or GitHub App with appropriate permissions
23+
- For metrics: Read access to target repositories and organizations
24+
- For webhooks: A publicly accessible endpoint to receive GitHub webhook events
25+
- Network connectivity to GitHub API endpoints, for example, `api.github.com` or your GitHub Enterprise instance
26+
27+
{{< admonition type="note" >}}
28+
`otelcol.receiver.github` is a wrapper over the upstream OpenTelemetry Collector [`github`][] receiver.
29+
Bug reports or feature requests will be redirected to the upstream repository, if necessary.
30+
31+
[`github`]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/{{< param "OTEL_VERSION" >}}/receiver/githubreceiver
32+
{{< /admonition >}}
33+
34+
## Usage
35+
36+
```alloy
37+
otelcol.receiver.github "<LABEL>" {
38+
scraper {
39+
github_org = "<GITHUB_ORG>"
40+
auth {
41+
authenticator = <AUTH_HANDLER>
42+
}
43+
}
44+
45+
output {
46+
metrics = [...]
47+
}
48+
}
49+
```
50+
51+
## Arguments
52+
53+
You can use the following arguments with `otelcol.receiver.github`:
54+
55+
| Name | Type | Description | Default | Required |
56+
| --------------------- | ---------- | ---------------------------------------------------- | ------- | -------- |
57+
| `collection_interval` | `duration` | How often to scrape metrics from GitHub. | `"30s"` | no |
58+
| `initial_delay` | `duration` | Defines how long the receiver waits before starting. | `"0s"` | no |
59+
60+
## Blocks
61+
62+
You can use the following blocks with `otelcol.receiver.github`:
63+
64+
| Block | Description | Required |
65+
| -------------------------------- | -------------------------------------------------------------------------- | -------- |
66+
| [`output`][output] | Configures where to send received telemetry data. | yes |
67+
| [`debug_metrics`][debug_metrics] | Configures the metrics that this component generates to monitor its state. | no |
68+
| [`scraper`][scraper] | Configures the GitHub scraper. | no |
69+
| `scraper` > [`auth`][auth] | Configures authentication for GitHub API. | yes |
70+
| `scraper` > [`metrics`][metrics] | Configures which metrics to collect. | no |
71+
| [`webhook`][webhook] | Configures webhook receiver for GitHub Actions events. | no |
72+
73+
The > symbol indicates deeper levels of nesting.
74+
For example, `scraper` > `auth` refers to an `auth` block defined inside a `scraper` block.
75+
76+
[scraper]: #scraper
77+
[webhook]: #webhook
78+
[output]: #output
79+
[debug_metrics]: #debug_metrics
80+
[auth]: #auth
81+
[metrics]: #metrics
82+
83+
### `scraper`
84+
85+
The `scraper` block configures the GitHub metrics scraper.
86+
87+
You can use the following arguments:
88+
89+
| Name | Type | Description | Default | Required |
90+
| -------------- | -------- | ---------------------------------------------------- | ------- | -------- |
91+
| `github_org` | `string` | GitHub organization or user to scrape metrics from. | | yes |
92+
| `endpoint` | `string` | GitHub API endpoint for GitHub Enterprise instances. | | no |
93+
| `search_query` | `string` | Custom search query to filter repositories. | | no |
94+
95+
### `auth`
96+
97+
The `auth` block configures authentication for the GitHub API.
98+
99+
You can use the following arguments:
100+
101+
| Name | Type | Description | Default | Required |
102+
| --------------- | -------------------------- | ------------------------------------------------ | ------- | -------- |
103+
| `authenticator` | `capsule(otelcol.Handler)` | Auth handler from an `otelcol.auth.*` component. | | yes |
104+
105+
### `metrics`
106+
107+
The `metrics` block allows you to enable or disable specific metrics. Each metric is configured with a nested block.
108+
109+
Available metrics:
110+
111+
| Metric Name | Description | Default |
112+
| ----------------------------- | ---------------------------------------------- | ------- |
113+
| `vcs.change.count` | Number of changes or pull requests by state. | `true` |
114+
| `vcs.change.duration` | Time a change spent in various states. | `true` |
115+
| `vcs.change.time_to_approval` | Time it took for a change to get approved. | `true` |
116+
| `vcs.change.time_to_merge` | Time it took for a change to be merged. | `true` |
117+
| `vcs.contributor.count` | Number of unique contributors to a repository. | `false` |
118+
| `vcs.ref.count` | Number of refs or branches in a repository. | `true` |
119+
| `vcs.ref.lines_delta` | Number of lines changed in a ref. | `true` |
120+
| `vcs.ref.revisions_delta` | Number of commits or revisions in a ref. | `true` |
121+
| `vcs.ref.time` | Time since the ref was created. | `true` |
122+
| `vcs.repository.count` | Number of repositories in an organization. | `true` |
123+
124+
Each metric can be configured with:
125+
126+
```alloy
127+
metrics {
128+
vcs.change.count {
129+
enabled = true
130+
}
131+
vcs.contributor.count {
132+
enabled = false
133+
}
134+
}
135+
```
136+
137+
### `webhook`
138+
139+
The `webhook` block configures webhook reception for GitHub Actions events.
140+
141+
When enabled, this block allows the receiver to convert GitHub Actions workflow and job events into traces.
142+
143+
{{< admonition type="note" >}}
144+
Secure your webhook endpoint with a secret and protect it with appropriate network security measures.
145+
{{< /admonition >}}
146+
147+
You can use the following arguments:
148+
149+
| Name | Type | Description | Default | Required |
150+
| --------------------- | ------------- | ---------------------------------------------------------- | ------------------ | -------- |
151+
| `endpoint` | `string` | The `host:port` to listen for webhooks. | `"localhost:8080"` | no |
152+
| `path` | `string` | URL path for webhook events. | `"/events"` | no |
153+
| `health_path` | `string` | URL path for health checks. | `"/health"` | no |
154+
| `include_span_events` | `bool` | Whether to attach raw webhook event JSON as span events. | `false` | no |
155+
| `secret` | `string` | Secret for validating webhook signatures. | | no |
156+
| `service_name` | `string` | Service name for traces from this receiver. | | no |
157+
| `required_headers` | `map(string)` | Required headers that must be present on webhook requests. | | no |
158+
159+
### `output`
160+
161+
{{< badge text="Required" >}}
162+
163+
{{< docs/shared lookup="reference/components/output-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
164+
165+
### `debug_metrics`
166+
167+
{{< docs/shared lookup="reference/components/otelcol-debug-metrics-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
168+
169+
## Exported fields
170+
171+
`otelcol.receiver.github` doesn't export any fields.
172+
173+
## Component health
174+
175+
`otelcol.receiver.github` is reported as unhealthy if the GitHub API can't be reached or authentication fails.
176+
177+
## Debug information
178+
179+
`otelcol.receiver.github` doesn't expose additional debug info.
180+
181+
## Example
182+
183+
### Basic configuration
184+
185+
This example scrapes metrics from a GitHub organization:
186+
187+
```alloy
188+
otelcol.auth.bearer "github" {
189+
token = env("GITHUB_PAT")
190+
}
191+
192+
otelcol.receiver.github "default" {
193+
collection_interval = "5m"
194+
195+
scraper {
196+
github_org = "grafana"
197+
search_query = "org:grafana topic:observability"
198+
199+
auth {
200+
authenticator = otelcol.auth.bearer.github.handler
201+
}
202+
203+
metrics {
204+
vcs.change.count {
205+
enabled = true
206+
}
207+
vcs.change.time_to_merge {
208+
enabled = true
209+
}
210+
vcs.repository.count {
211+
enabled = true
212+
}
213+
vcs.contributor.count {
214+
enabled = true
215+
}
216+
}
217+
}
218+
219+
output {
220+
metrics = [otelcol.exporter.prometheus.default.input]
221+
}
222+
}
223+
224+
otelcol.exporter.prometheus "default" {
225+
forward_to = [prometheus.remote_write.default.receiver]
226+
}
227+
228+
prometheus.remote_write "default" {
229+
endpoint {
230+
url = "https://prometheus.example.com/api/v1/write"
231+
}
232+
}
233+
```
234+
235+
### With webhook for GitHub Actions traces
236+
237+
This example adds webhook support to receive GitHub Actions workflow events as traces:
238+
239+
```alloy
240+
otelcol.auth.bearer "github" {
241+
token = env("GITHUB_PAT")
242+
}
243+
244+
otelcol.receiver.github "default" {
245+
scraper {
246+
github_org = "my-org"
247+
auth {
248+
authenticator = otelcol.auth.bearer.github.handler
249+
}
250+
}
251+
252+
webhook {
253+
endpoint = "0.0.0.0:8080"
254+
path = "/github/webhooks"
255+
health_path = "/health"
256+
secret = env("GITHUB_WEBHOOK_SECRET")
257+
}
258+
259+
output {
260+
metrics = [otelcol.exporter.otlphttp.default.input]
261+
traces = [otelcol.exporter.otlphttp.default.input]
262+
}
263+
}
264+
265+
otelcol.exporter.otlphttp "default" {
266+
client {
267+
endpoint = "https://otlp.example.com"
268+
}
269+
}
270+
```
271+
272+
### GitHub Enterprise
273+
274+
For GitHub Enterprise instances, specify the custom endpoint:
275+
276+
```alloy
277+
otelcol.auth.bearer "github_enterprise" {
278+
token = env("GHE_PAT")
279+
}
280+
281+
otelcol.receiver.github "enterprise" {
282+
scraper {
283+
github_org = "my-enterprise-org"
284+
endpoint = "https://github.mycompany.com"
285+
286+
auth {
287+
authenticator = otelcol.auth.bearer.github_enterprise.handler
288+
}
289+
}
290+
291+
output {
292+
metrics = [otelcol.exporter.prometheus.default.input]
293+
}
294+
}
295+
```
296+
297+
<!-- START GENERATED COMPATIBLE COMPONENTS -->
298+
299+
## Compatible components
300+
301+
`otelcol.receiver.github` can accept arguments from the following components:
302+
303+
- Components that export [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-exporters)
304+
305+
306+
{{< admonition type="note" >}}
307+
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly.
308+
Refer to the linked documentation for more details.
309+
{{< /admonition >}}
310+
311+
<!-- END GENERATED COMPATIBLE COMPONENTS -->

‎go.mod‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -968,6 +968,11 @@ require (
968968

969969
require github.com/open-telemetry/opentelemetry-collector-contrib/receiver/awss3receiver v0.139.0
970970

971+
require (
972+
github.com/open-telemetry/opentelemetry-collector-contrib/receiver/awss3receiver v0.139.0
973+
github.com/open-telemetry/opentelemetry-collector-contrib/receiver/githubreceiver v0.138.0
974+
)
975+
971976
require (
972977
cyphar.com/go-pathrs v0.2.1 // indirect
973978
github.com/DataDog/datadog-agent/comp/api/api/def v0.73.0-devel.0.20251030121902-cd89eab046d6 // indirect
@@ -984,6 +989,7 @@ require (
984989
github.com/DataDog/datadog-agent/pkg/opentelemetry-mapping-go/otlp/rum v0.73.0-devel.0.20251030121902-cd89eab046d6 // indirect
985990
github.com/DataDog/datadog-agent/pkg/util/defaultpaths v0.69.3 // indirect
986991
github.com/DataDog/datadog-agent/pkg/util/quantile v0.73.0-devel.0.20251030121902-cd89eab046d6 // indirect
992+
github.com/Khan/genqlient v0.8.1 // indirect
987993
github.com/aws/aws-sdk-go-v2/service/sqs v1.42.11 // indirect
988994
github.com/digitalocean/go-metadata v0.0.0-20250129100319-e3650a3df44b // indirect
989995
github.com/go-openapi/swag/cmdutils v0.25.1 // indirect
@@ -997,11 +1003,13 @@ require (
9971003
github.com/go-openapi/swag/stringutils v0.25.1 // indirect
9981004
github.com/go-openapi/swag/typeutils v0.25.1 // indirect
9991005
github.com/go-openapi/swag/yamlutils v0.25.1 // indirect
1006+
github.com/google/go-github/v76 v76.0.0 // indirect
10001007
github.com/linode/go-metadata v0.2.2 // indirect
10011008
github.com/mitchellh/hashstructure v1.1.0 // indirect
10021009
github.com/open-telemetry/opamp-go v0.22.0 // indirect
10031010
github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages v0.139.0 // indirect
10041011
github.com/twmb/franz-go/pkg/kadm v1.17.1 // indirect
1012+
github.com/vektah/gqlparser/v2 v2.5.22 // indirect
10051013
golang.org/x/telemetry v0.0.0-20251008203120-078029d740a8 // indirect
10061014
)
10071015

0 commit comments

Comments
 (0)