gitproviderreceiver

README

Git Provider Receiver

Status
Stability	development: metrics
Distributions	[liatrio]
Issues

[liatrio]:

The Git Provider receiver scrapes data from Git vendors.

As a starting point, this receiver can infer many of the same core git metrics across vendors, while being able to receive additional data specific to vendors.

The current default set of metrics common across all vendors can be found in documentation.md.

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

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 run into significantly more rate limiting.

gitprovider:
    collection_interval: <duration> #default = 30s recommended 300s
    scrapers:
        <scraper1>:
        <scraper2>:
        ...

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

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

receivers:
    gitprovider:
        initial_delay: 1s
        collection_interval: 300s
        scrapers:
            # GitHub Scraper settings
            github:
                metrics:
                    git.repository.contributor.count:
                        enabled: true
                    git.repository.cve.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
            # GitLab scraper settings
            gitlab:
                metrics:
                    git.repository.contributor.count:
                        enabled: true
                    git.repository.cve.count:
                        enabled: true
                gitlab_org: myfancyorg
                search_topic: "o11yalltheway"
                auth:
                    authenticator: bearertokenauth/gitlab

service:
    extensions: [bearertokenauth/github, bearertokenauth/gitlab]
    pipelines:
        metrics:
            receivers: [..., gitprovider]
            processors: []
            exporters: [...]

Github PAT basic permissions

The queries under the hood are all read queries, there is no write. They read repos, orgs, branches, commits, metadata, issues, pull requests, and GHAS security events.

It is recommend to use the GitHub App Authentication Extension for authentication. GitHub Apps offer better security through OAUTH, provide more granular control over permissions, and increase rate limits.

However, if you do decide to use a PAT, we recommend you use a Fine Grained Token because these tokens allow you to set read only permissions.

Give your token the permissions below...

This receiver is developed upstream in the liatrio-otel-collector distribution where a quick start exists with an example config

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

The available scrapers are:

Scraper	Description
[github]	Git Metrics from GitHub
[gitlab]	Git Metrics from GitLab

GitHub Metrics

The current metrics available via scraping from GitHub are:

• Repository count
• Repository contributor count
• Repository branch count
• Repository branch time
• Repository branch commit aheadby count
• Repository branch commit behindby count
• Repository branch line addition count
• Repository branch line deletion count
• Repository pull request open time
• Repository pull request time to merge
• Repository pull request time to approval
• Repository pull request count | stores an attribute of pull_request.state equal to open or merged
• Repository CVE count | stores an attribute of cve.severity equal to low, medium, high, or critical

GitLab Metrics

The current metrics available via scraping from GitLab are:

• Repository count
• Repository contributor count
• Repository branch count
• Repository branch time
• Repository branch commit aheadby count
• Repository branch commit behindby count
• Repository branch line addition count
• Repository branch line deletion count
• Repository pull request open time
• Repository pull request time to merge
• Repository pull request time to approval
• Repository pull request count | stores an attribute of pull_request.state equal to open or merged
• Repository CVE count | stores an attribute of cve.severity equal to low, medium, high, or critical

Updating tests

After using make gen you may find your tests failing. This could be due to the expected_happy_path.yaml missing some of the changes from your code, or being out of order.

You can resolve this manually by updating the file, or by regenerating it by uncommenting the lines starting with //golden.WriteMetrics in your test files, and rerunning the unit tests. Comment the lines out again and commit the new changes.

Documentation

Index

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

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for the git provider receiver

Types

type Config

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

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