githubreceiver

README

GitHub Receiver

Status
Stability	development: traces
	alpha: metrics
Distributions	contrib
Issues
Code Owners	@adrielp, @andrzej-stencel, @crobert-1, @TylerHelmuth

The GitHub receiver receives data from GitHub.

The current default set of metrics can be found in documentation.md.

These metrics can be used as leading indicators (capabilities) to the DORA metrics; helping provide insight into modern-day engineering practices.

Metrics - Getting Started

The collection interval is common to all scrapers and is set to 30 seconds by default.

Note: Generally speaking, if the vendor allows for anonymous API calls, then you won't have to configure any authentication, but you may only see public repositories and organizations. You may also run into significantly more rate limiting.

github:
    collection_interval: <duration> #default = 30s recommended 300s
    scrapers:
        scraper/config-1:
        scraper/config-2:
        ...

A more complete example using the GitHub scrapers with authentication is as follows:

extensions:
    bearertokenauth/github:
        token: ${env:GH_PAT}

receivers:
    github:
        initial_delay: 1s
        collection_interval: 60s
        scrapers:
            scraper:
                metrics:
                    vcs.repository.contributor.count:
                        enabled: true
                github_org: myfancyorg
                search_query: "org:myfancyorg topic:o11yalltheway" #Recommended optional query override, defaults to "{org,user}:<github_org>"
                endpoint: "https://selfmanagedenterpriseserver.com"
                auth:
                    authenticator: bearertokenauth/github
service:
    extensions: [bearertokenauth/github]
    pipelines:
        metrics:
            receivers: [..., github]
            processors: []
            exporters: [...]

A Grafana Dashboard exists on the marketplace for metrics from this receiver and can be found here.

Scraping

Important:

• The GitHub scraper does not emit metrics for branches that have not had changes since creation from the default branch (trunk).
• Due to GitHub API limitations, it is possible for the branch time metric to change when rebases occur, recreating the commits with new timestamps.

For additional context on GitHub scraper limitations and inner workings please see the Scraping README.

Traces - Getting Started

Workflow tracing support is actively being added to the GitHub receiver. This is accomplished through the processing of GitHub Actions webhook events for workflows and jobs. The workflow_job and workflow_run event payloads are then constructed into trace telemetry.

Each GitHub Action workflow or job, along with its steps, are converted into trace spans, allowing the observation of workflow execution times, success, and failure rates.

Configuration

IMPORTANT: At this time the tracing portion of this receiver only serves a health check endpoint.

The WebHook configuration exposes the following settings:

• endpoint: (default = localhost:8080) - The address and port to bind the WebHook to.
• path: (default = /events) - The path for Action events to be sent to.
• health_path: (default = /health) - The path for health checks.
• secret: (optional) - The secret used to validates the payload.
• required_header: (optional) - The required header key and value for incoming requests.

The WebHook configuration block also accepts all the [confighttp][cfghttp] settings.

An example configuration is as follows:

receivers:
    github:
        scrapers:
            ... <scraper configuration>: # Scraper configurations are required until Tracing functionality is complete.
        webhook:
            endpoint: localhost:19418
            path: /events
            health_path: /health
            secret: ${env:SECRET_STRING_VAR}
            required_header:
                key: "X-GitHub-Event"
                value: "action"

For tracing, all configuration is set under the webhook key. The full set of exposed configuration values can be found in [config.go][config.go].

[config.go] ./config.go [cfghttp]: https://pkg.go.dev/go.opentelemetry.io/collector/config/confighttp#ServerConfig

Documentation

Index

• func NewFactory() receiver.Factory
• type Config
  • func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error
  • func (cfg *Config) Validate() error
• type RequiredHeader
• type WebHook

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for the github receiver

Types

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	Scrapers                       map[string]internal.Config `mapstructure:"scrapers"`
	metadata.MetricsBuilderConfig  `mapstructure:",squash"`
	WebHook                        WebHook `mapstructure:"webhook"`
}

Config that is exposed to this github receiver through the OTEL config.yaml

func (*Config) Unmarshal

func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error

Unmarshal a config.Parser into the config struct.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate the configuration passed through the OTEL config.yaml

type RequiredHeader

type RequiredHeader struct {
	Key   string `mapstructure:"key"`
	Value string `mapstructure:"value"`
}

type WebHook

type WebHook struct {
	confighttp.ServerConfig `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct
	Path                    string                   `mapstructure:"path"`            // path for data collection. Default is /events
	HealthPath              string                   `mapstructure:"health_path"`     // path for health check api. Default is /health_check
	RequiredHeader          RequiredHeader           `mapstructure:"required_header"` // optional setting to set a required header for all requests to have
	Secret                  string                   `mapstructure:"secret"`          // secret for webhook
}