GitHub Actions OpenTelemetry

This action sends metrics and traces of GitHub Actions to an OpenTelemetry Protocol (OTLP) endpoint. It helps you monitor and analyze GitHub Actions.

Features Summary

• 📊 Collects Metrics of GitHub Actions workflows and job execution times
• 🔍 Collects Traces of GitHub Actions workflow, jobs, steps.
• 📦 Sends data to any OTLP-compatible backend for monitoring and observability
• 🚀 Collect telemetry without modifying existing workflows

Metrics

Descriptor Name	Description
github.workflow.duration	Duration of workflow
github.job.duration	Duration of job
github.job.queued_duration	Duration of queued job

Each metric has associated attributes.

Traces

Traces include several attributes to help identify and analyze workflow execution:

• Workflow-level attributes: run_id, run_attempt, repository, url
• Job-level attributes: job.id, job.conclusion, runner.name, runner.group

You can find a trace by the run_id attribute attached to the root span. run_id is visible in the workflow results URL. For example, if the URL is:

https://github.com/paper2/github-actions-opentelemetry/actions/runs/12246387114

Then the run_id is 12246387114.

Adding Custom Resource Attributes

You can add custom attributes to all traces and metrics using the OTEL_RESOURCE_ATTRIBUTES environment variable. This is useful for adding context like environment, or team information:

env:
OTEL_RESOURCE_ATTRIBUTES: 'environment=production,team=backend'

These custom attributes will be included as resource attributes in all exported telemetry data.

Trace ID Summary

After the action completes, you'll see the workflow trace ID displayed in the GitHub Actions summary for easy access:

How it works

This action creates metrics and traces of GitHub Actions workflows and sends them to an OTLP endpoint. It uses the GitHub API to collect data about completed workflows and jobs. The action then sends this data to the OTLP endpoint for monitoring and observability.

sequenceDiagram
participant TW as Target Workflow
participant GAOW as GitHub Actions OpenTelemetry Workflow
participant GA as GitHub API
participant OE as OTLP Endpoint
TW ->> TW: Complete Workflow
TW ->> GAOW: Trigger by workflow_run
GAOW ->> GA: Get Target Workflow Data
GAOW ->> OE: Send Metrics and Traces

Loading

Setup Instructions

1. Create OTLP Endpoint: Set up an OTLP backend to receive telemetry data (e.g., Jaeger, Prometheus, or other monitoring tools).
2. Add a Workflow: Create a new workflow file and use this action triggered by workflow_run because this action collects telemetry of completed workflows.

GitHub Actions Examples

Option 1: Monitor Other Workflows

Monitor completed workflows triggered by workflow_run events:

name: Send Telemetry after Other Workflowon:
workflow_run:
# Specify the workflows you want to collect telemetry.workflows:
- Check Transpiled JavaScript
- Continuous Integration
- CodeQL
- Lint Codebase# This action uses completed workflow for making traces and metrics.types:
- completedpermissions:
# Required for private repositoriesactions: readjobs:
send-telemetry:
name: Send CI Telemetryruns-on: ubuntu-lateststeps:
- name: Runid: runuses: paper2/github-actions-opentelemetry@mainenv:
OTEL_SERVICE_NAME: github-actions-opentelemetryOTEL_EXPORTER_OTLP_ENDPOINT: https://collector-example.com# Additional OTLP headers. Useful for OTLP authentication.# e.g.# New Relic: api-key=YOUR_NEWRELIC_API_KEY# Google Cloud Run: Authorization=Bearer <value of $(gcloud auth print-identity-token)># Basic Authentication: Authorization=Basic <base64-encoded value of userid:password>OTEL_EXPORTER_OTLP_HEADERS:
api-key=${ secrets.API_KEY },other-config-value=valueOTEL_RESOURCE_ATTRIBUTES: 'environment=ci,team=backend'with:
# Required for collecting workflow dataGITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Option 2: Monitor Current Workflow (Experimental)

Monitor the current workflow by running this action as the last step:

name: CI with Built-in Telemetryon:
push:
branches: [main]pull_request:
branches: [main]jobs:
build:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run buildtest:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test# Telemetry job runs after all other jobs completetelemetry:
runs-on: ubuntu-latestneeds: [build, test] # Wait for other jobs to completeif: always() # Run even if other jobs failsteps:
- name: Send Telemetryuses: paper2/github-actions-opentelemetry@mainenv:
OTEL_SERVICE_NAME: github-actions-opentelemetryOTEL_EXPORTER_OTLP_ENDPOINT: https://collector-example.com# Additional OTLP headers. Useful for OTLP authentication.# e.g.# New Relic: api-key=YOUR_NEWRELIC_API_KEY# Google Cloud Run: Authorization=Bearer <value of $(gcloud auth print-identity-token)># Basic Authentication: Authorization=Basic <base64-encoded value of userid:password>OTEL_EXPORTER_OTLP_HEADERS:
api-key=${ secrets.API_KEY },other-config-value=valueOTEL_RESOURCE_ATTRIBUTES: 'environment=ci,team=backend'with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Configuration

To configure the action, you need to set the following environment variables:

Environment Variable	Required	Default Value	Description
OTEL_SERVICE_NAME	Yes	-	Service name.
OTEL_EXPORTER_OTLP_ENDPOINT	Yes	-	OTLP Endpoint for Traces and Metrics. e.g., https://collector-example.com
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	No	-	OTLP Endpoint for Metrics instead of OTEL_EXPORTER_OTLP_ENDPOINT.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	No	-	OTLP Endpoint for Traces instead of OTEL_EXPORTER_OTLP_ENDPOINT.
OTEL_EXPORTER_OTLP_HEADERS	No	-	Additional OTLP headers. Useful for authentication. e.g., "api-key=key,other-config-value=value"
OTEL_RESOURCE_ATTRIBUTES	No	-	Additional resource attributes for traces and metrics. e.g., "environment=production,team=backend"
FEATURE_TRACE	No	true	Enable trace feature.
FEATURE_METRICS	No	true	Enable Metrics feature.
OTEL_LOG_LEVEL	No	info	Log level.

This action relies on the OpenTelemetry SDK, which automatically reads OTEL_ environment variables from jobs.<job_id>.steps[*].env. The table above lists commonly used variables, but other variables defined in the OpenTelemetry Environment Variable Specification may also work depending on SDK support.

Getting Started

We prepared a Getting Started to create OpenTelemetry backend and run this action by using Google Cloud.

Limitations

There are some limitations that come from GitHub Actions Specification. See Specification page for details.

Development

Dev Container

You can run containers by devcontainer.

• Jaeger and Prometheus run for local testing.
  • Jaeger: http://localhost:16686
  • Prometheus: http://localhost:9090

Local test

You can run all tests below command.

npm run test

You can run a simple test. It is useful for checking output while developing.

npm run test-local

Compile

TypeScript codes must be compiled by ncc. You have changed code, run bellow the command.

npm run all

Note

This command creates index.js and more on the /dist directory. You must includes these artifacts on a commit because GitHub Actions uses these files.

Recommend to install GitHub CLI (gh)

Tests invoke real GitHub API. Unauthenticated users are subject to strict API rate limits. If gh command is installed and login is finished, token is automatically set for tests by vitest.config.ts.

the login command is below.

gh auth login

If you face below error, recommend to install GitHub CLI and login.

message: "API rate limit exceeded for xx.xx.xx.xx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
documentation_url: 'https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting'

Default Environment Variables for Testing

Some environment variables are set on vitest.config.ts.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request. Before contributing, ensure that your changes are well-documented and tested.

Support

If you encounter any issues or have questions, feel free to open an issue in the repository. We will do our best to assist you promptly.