Skip to content

Latest commit

 

History

History
75 lines (51 loc) · 4.25 KB

README.md

File metadata and controls

75 lines (51 loc) · 4.25 KB

Alloy Collector Distro

This directory contains the build configuration and generated code for the Alloy Collector Distro, an OpenTelemetry Collector distribution that embeds Alloy's OTel components and integrates with the Alloy CLI. This also means that it contains the generated build root of the Alloy project.

Overview

The Alloy Collector Distro is built using the OpenTelemetry Collector Builder (OCB) tool. Components are defined in an OCB configuration file, and the build process generates the necessary Go code, including the main.go file and go.mod dependencies.

Directory Structure

collector/
├── builder-config.yaml        # OCB configuration file (source)
├── generate.go                # Entry point for code generation (source)
├── version.go                 # Exposes the current version of the collector distro (source)
├── generator/                 # Custom templating and generation code (source)
│   ├── generator.go          # Generator tool that post-processes OCB output
│   └── main_alloy.tpl        # Template for main_alloy.go
│
├── main.go                    # Generated by OCB (DO NOT EDIT)
├── main_alloy.go              # Generated by generator (DO NOT EDIT)
├── main_others.go             # Generated by OCB (DO NOT EDIT)
├── main_windows.go            # Generated by OCB (DO NOT EDIT)
├── components.go              # Generated by OCB (DO NOT EDIT)
├── go.mod                     # Generated by OCB (DO NOT EDIT)
└── go.sum                     # Generated by OCB (DO NOT EDIT)

Build Process

The build process consists of three main steps:

1. OCB Generation (go run go.opentelemetry.io/collector/cmd/builder@${BUILDER_VERSION})

The BUILDER_VERSION is defined in the root Makefile, and should be kept in sync with our general OTel component versioning

The OCB tool reads builder-config.yaml and generates:

  • main.go - The main entry point for the collector
  • components.go - Component factories and registrations
  • go.mod and go.sum - Module dependencies
  • Other platform-specific main files (main_others.go, main_windows.go)

The builder-config.yaml file defines:

  • General collector distribution metadata
  • The Open Telemetry components to include in the distribution (receivers/processors/exporters etc)
  • Replace directives, which are automated/generated to keep in sync with dependency-replacements.yaml in the root of the project

2. Go Module Tidying (go mod tidy)

Ensures the generated go.mod is properly formatted and all dependencies are resolved.

3. Custom Generator (go run ./generator/generator.go)

The custom generator performs two tasks:

  1. Generates main_alloy.go - Creates a wrapper that integrates the OTel collector command into Alloy's CLI as a subcommand (alloy otel)
  2. Modifies main.go - Replaces otelcol.NewCommand(params) with newAlloyCommand(params) to use the Alloy-integrated command

Building Locally

When building locally via make alloy, there is a pre-req on the generated otel collector files being up-to-date. Generally, no action is needed unless you are doing active development on this area. If that is the case, then locally you will need to manually trigger generation prior to running make alloy.

To manually trigger generation:

make generate-otel-collector-distro

CI Considerations

If your work involves anything that would modify the generated files, please commit them with your changes before pushing to github. We have a github workflow that will check that the output of the collector generation matches what has been checked in, and this will fail if you do not include changes to these files.

A Note On Replace Directives

The replaces section in builder-config.yaml must be kept in sync with the replace directives in the root go.mod file as well as the go.mod file in the alloy engine extension. The Alloy project uses the dependency-replacements.yaml file found in the root of the project to generate replace directives. If you modify a replacement, please run make generate-module-dependencies to sync things up. There is also a github workflow that will check against this.