FriendsOfOpenTelemetry/opentelemetry-nix

OpenTelemetry tools & library for Nix

OpenTelemetry for Nix

This repository exposes various OpenTelemetry related packages and a library to build custom OpenTelemetry collectors

Packages

• otel-collector-builder - Generates a custom OpenTelemetry Collector binary based on a given configuration
• tracetest - Build integration and end-to-end tests in minutes using OpenTelemetry and trace-based testing
• tracepusher - Generate and push OpenTelemetry Trace data to an OTEL collector in JSON format
• har-to-otel - Chrome DevTools HAR file to OpenTelemetry converter

Library

• buildOtelCollector: build a custom OpenTelemetry collector
• mkOtelCollectorBuilderConfiguration: create an OpenTelemetry collector builder configuration file

Usage

This repository uses Nix "flake" feature and does not provider other usages. Please refer to the documentation to enable it.

Each package is exposed as an application, you can run each one of them with nix run:

nix run github:FriendsOfOpenTelemtry/opentelemetry-nix#otel-collector-builder
nix run github:FriendsOfOpenTelemtry/opentelemetry-nix#{package-name}

Please refer to the nix run documentation for wider use.

Those packages are also available in an overlay.

Flake

Import the repository as input:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  opentelemetry-nix.url = "github:FriendsOfOpenTelemetry/opentelemetry-nix";
};

Import the overlay:

pkgs = import inputs.nixpkgs {
  inherit system;
  overlays = [
    inputs.opentelemetry-nix.overlays.default
  ];
};

Use the packages:

# for example in a devShell:
devShells.x86_64-linux.default = pkgs.mkShell {
  packages = [ pkgs.otel-collector-builder ];
}

Library

buildOtelCollector: Build a custom OpenTelemetry collector

# for example as a package:
packages.x86_64-linux.default = pkgs.buildOtelCollector {
  pname = "otel-collector-debugexporter";
  version = "1.0.0";
  config = {
    exporters = [
      { gomod = "go.opentelemetry.io/collector/exporter/debugexporter v0.90.0"; }
    ];
  };
  vendorHash = "sha256-2g0xe9kLJEbgU9m+2jmWA5Gym7EYHlelsyU0hfLViUY=";
}

Options

• pname: The package name.
• version: The package version.
• config: The configuration that will be passed to mkOtelCollectorBuilderConfiguration. It must match the exact YAML representation of the configuration options mentionned in the builder documentation for extensions, exporters, receivers, processors & replaces options.
• vendorHash: The hash of the custom collector sources & modules.
• otelBuilderPackage: The OpenTelemetry collector builder package to use, defaults the one available in this flake.
• meta: The meta attributes to use to describe the custom OpenTelemetry collector package.

mkOtelCollectorBuilderConfiguration: Create an OpenTelemetry collector builder configuration file

# for example as a package:
packages.x86_64-linux.default = pkgs.mkOtelCollectorBuilderConfiguration {
  pname = "otel-collector-debugexporter";
  version = "1.0.0";
  config = {
    exporters = [
      { gomod = "go.opentelemetry.io/collector/exporter/debugexporter v0.90.0"; }
    ];
  };
}

Options

• pname: The configuration name.
• version: The configuration version.
• config: The configuration to use. It must match the exact YAML representation of the configuration options mentionned in the builder documentation for extensions, exporters, receivers, processors & replaces options.
• goPackage: The go package to use when building the generated configuration file with the OpenTelemetry collector builder.

Cachix

Cachix is used to store package binaries.

To use our cache, run cachix use opentelemetry.

Refer to the documentation to install Cachix.