https://github.com/krzko/setup-telemetry

The Set Up Telemetry action provides deterministic OpenTelemetry trace IDs, job IDs and traceparent for GitHub Actions workflow telemetry.
https://github.com/krzko/setup-telemetry

actions distributed-tracing ids observability opentelemetry

Last synced: about 1 month ago
JSON representation

The Set Up Telemetry action provides deterministic OpenTelemetry trace IDs, job IDs and traceparent for GitHub Actions workflow telemetry.

• Host: GitHub
• URL: https://github.com/krzko/setup-telemetry
• Owner: krzko
• License: apache-2.0
• Created: 2024-03-28T03:08:35.000Z (8 months ago)
• Default Branch: main
• Last Pushed: 2024-05-09T05:34:15.000Z (6 months ago)
• Last Synced: 2024-09-27T06:43:14.544Z (about 2 months ago)
• Topics: actions, distributed-tracing, ids, observability, opentelemetry
• Language: Go
• Homepage:
• Size: 209 MB
• Stars: 6
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
# Setup Telemetry Action

This action exports trace and job IDs, and sets up a traceparent for use in GitHub Actions workflows to enable telemetry and tracing. It is intended to be used in conjunction with the [OpenTelemetry Collector GitHub Actions Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/27460). This receiver processes GitHub Actions webhook events to observe workflows and jobs, converting them into trace telemetry for detailed observability.

It is important to note that `job-id` and `job-name` are not directly accessible through the [GitHub environment variables](https://docs.github.com/en/actions/learn-github-actions/variables).

The `job-name` output uses the default `name` or the name provided by `run-name`, rather than the rendered name that might be applied by a composite workflow or matrix strategy.

This action provides a consistent and accessible method to retrieve these values for further use in your workflow, which is especially useful in complex workflows where these values need to be explicitly managed or passed between jobs.

Trace IDs and job span IDs are generated in a deterministic fashion from the associated run ID and run attempt, with job span IDs also incorporating the job name. This deterministic generation ensures consistent and predictable identifiers for tracing and telemetry across workflow executions.

## GitHub Actions Receiver

The GitHub Actions Receiver processes GitHub Actions webhook events to observe workflows and jobs. It handles `workflow_job` and `workflow_run` event payloads, transforming them into trace telemetry. This allows the observation of workflow execution times, success, and failure rates. If a secret is configured (recommended), it validates the payload ensuring data integrity before processing.

## Usage

### Pre-requisites

Create a workflow `.yml` file in your repository's `.github/workflows` directory. For more information, see the GitHub Help Documentation for [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).

### Inputs

| Name                      | Description                                                         | Required |

|----------------------------|---------------------------------------------------------------------|----------|

| `github-token`             | A token that can be used with the GitHub API. Default is `${{ github.token }}`. | Optional |

| `observability-backend-url`| Base URL to the observability backend, to create a trace link.     | Optional |

### Outputs

| Output          | Description                                                       |

|-----------------|-------------------------------------------------------------------|

| `created-at`    | The timestamp when the workflow run was created.                  |

| `job-id`        | The ID of the GitHub Actions job.                                |

| `job-name`      | The name of the GitHub Actions job.                              |

| `job-span-id`   | The generated span ID for the job.                               |

| `started-at`    | The timestamp when the workflow run started.                     |

| `traceparent`   | The W3C Trace Context traceparent value for the workflow run.    |

| `trace-id`      | The generated trace ID for the workflow run.                     |

| `trace-link`    | The URL of the observability backend with appended `trace-id`.   |

### Example Usage

```yaml

name: Test and Build

on:

  push:

permissions: read-all

env:

  honeycomb-url: https://ui.honeycomb.io/foo/environments/dev/datasets/github.com.foo/trace?trace_id=

  otel-exporter-otlp-endpoint: otelcol.foo.corp:443

  otel-service-name: o11y.workflows

  otel-resource-attributes: deployment.environent=dev,service.version=0.1.0

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - name: Setup telemetry

        id: setup-telemetry

        uses: krzko/[email protected]

        with:

          observability-backend-url: ${{ env.honeycomb-url }}

      - name: Checkout

        uses: actions/checkout@v4

      - run: # do_some_work

      - name: Export job telemetry

        if: always()

        uses: krzko/[email protected]

        with:

          created-at: ${{ steps.setup-telemetry.outputs.created-at }}

          job-status: ${{ job.status }}

          job-name: ${{ steps.setup-telemetry.outputs.job-name }}

          otel-exporter-otlp-endpoint: ${{ env.otel-exporter-otlp-endpoint }}

          otel-resource-attributes: "foo.new_attribute=123,${{ env.otel-resource-attributes }}"

          otel-service-name: ${{ env.otel-service-name }}

          started-at: ${{ steps.setup-telemetry.outputs.started-at }}

          traceparent: ${{ steps.setup-telemetry.outputs.traceparent }}

  build:

    runs-on: ubuntu-latest

    steps:

      - name: Setup telemetry

        id: setup-telemetry

        uses: krzko/[email protected]

        with:

          observability-backend-url: ${{ env.honeycomb-url }}

      - name: Checkout

        uses: actions/checkout@v4

      - run: # do_some_work

      - name: Export job telemetry

        if: always()

        uses: krzko/[email protected]

        with:

          created-at: ${{ steps.setup-telemetry.outputs.created-at }}

          job-status: ${{ job.status }}

          job-name: ${{ steps.setup-telemetry.outputs.job-name }}

          otel-exporter-otlp-endpoint: ${{ env.otel-exporter-otlp-endpoint }}

          otel-resource-attributes: "foo.new_attribute=123,${{ env.otel-resource-attributes }}"

          otel-service-name: ${{ env.otel-service-name }}

          started-at: ${{ steps.setup-telemetry.outputs.started-at }}

          traceparent: ${{ steps.setup-telemetry.outputs.traceparent }}

```

In this workflow, the `Setup telemetry` action is used to generate and output the trace ID, job ID, job name, job span ID, and traceparent, which can then be used in subsequent steps of the workflow, such as using the [krzko/export-job-telemetry](https://github.com/krzko/export-job-telemetry) action.

### Contributing

Contributions to `krzko/setup-telemetry` are welcome! Please refer to the repository's CONTRIBUTING.md for guidelines on how to submit contributions.

## License

The scripts and documentation in this project are released under the Apache License.