Las imágenes prediseñadas del Collector son prácticas pero amplias. La distribución contrib contiene cientos de componentes, la mayoría de los cuales nunca usarás, y la distribución core tiene muy pocos. Si quieres un binario más pequeño, una superficie de ataque reducida o un componente privado propio, puedes construir exactamente el Collector que necesitas con el OpenTelemetry Collector Builder (ocb). La entrada es un único manifiesto YAML, así que todo el proceso sigue siendo dirigido por configuración.

Cuándo construir el tuyo

• Quieres solo los componentes que usas, para una imagen más pequeña y menos dependencias que parchear.
• La política de seguridad te exige construir desde el código fuente y controlar la cadena de suministro.
• Necesitas un componente que no está en ninguna distribución oficial, como uno escrito internamente.

Si ninguno de estos casos aplica, usa las distribuciones oficiales. Construir el tuyo significa que asumes la tarea de reconstruir cuando los componentes reciben correcciones de seguridad.

Instala el builder

ocb es un programa de Go que se publica con cada versión del Collector. Descarga el binario para tu plataforma desde la página de releases de GitHub del Collector, o instálalo con Go:

go install go.opentelemetry.io/collector/cmd/builder@v0.163.0

Usa la misma versión para el builder y para los componentes. (La versión mostrada es un ejemplo; usa una release actual.) La toolchain de Go debe estar instalada para ejecutar una build. Consulta la guía de instalación en la documentación de OpenTelemetry para el nombre exacto del binario y los enlaces de descarga, porque difieren según la release.

Escribe el manifiesto

# builder-config.yaml
dist:
  name: otelcol-custom
  description: Custom OpenTelemetry Collector
  output_path: ./otelcol-custom
  # Opcional: la versión del Collector core contra la que construir
  # otelcol_version: 0.163.0

receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.163.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/filelogreceiver v0.163.0

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.163.0
  - gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.163.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/k8sattributesprocessor v0.163.0

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.163.0
  - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.163.0
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.163.0

extensions:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.163.0

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.0.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.0.0

Puntos clave:

• Cada entrada nombra un módulo de Go y una versión (gomod). Los componentes contrib viven bajo github.com/open-telemetry/opentelemetry-collector-contrib/..., y los core bajo go.opentelemetry.io/collector/....
• Las versiones de los componentes deben ser compatibles. Los componentes core, los componentes contrib y el builder se publican juntos; mantén todos en la misma release. Mezclar versiones causa errores de compilación.
• Los providers deciden qué fuentes de configuración están disponibles. Si quieres que funcionen ${env:VAR} y ${file:/path}, incluye envprovider y fileprovider. Un binario sin ellos no puede resolver esas referencias. Los módulos de providers usan sus propios números de versión (a menudo v1.x), así que búscalos para la release contra la que construyas.
• Las rutas y nombres de los módulos de los componentes pueden cambiar, así que cópialos del README de cada componente o del manifiesto de la propia distribución contrib en lugar de hacerlo de memoria.

Puedes usar replaces: para sustituir un módulo por un fork local, y las entradas gomod pueden apuntar a tus repositorios privados.

Construye

ocb --config builder-config.yaml
# o, si se instaló con go install:
builder --config builder-config.yaml

El directorio de salida contiene el código fuente de Go generado y un binario compilado, ./otelcol-custom/otelcol-custom. Ejecútalo con un archivo de configuración normal y comprueba qué está incluido:

./otelcol-custom/otelcol-custom components      # lista lo que se compiló
./otelcol-custom/otelcol-custom validate --config=config.yaml
./otelcol-custom/otelcol-custom --config=config.yaml

Si tu configuración referencia un componente que no se incluyó en la build, el Collector falla al arrancar y lo nombra. Añádelo al manifiesto y reconstruye.

Empaquétalo como imagen de contenedor

Un Dockerfile multietapa construye en una imagen de Go y copia el resultado en una base mínima:

FROM golang:1.24 AS build
WORKDIR /src
RUN go install go.opentelemetry.io/collector/cmd/builder@v0.163.0
COPY builder-config.yaml .
RUN CGO_ENABLED=0 builder --config builder-config.yaml

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /src/otelcol-custom/otelcol-custom /otelcol-custom
USER nonroot
ENTRYPOINT ["/otelcol-custom"]
CMD ["--config=/etc/otelcol/config.yaml"]

Usa una versión de Go que coincida con el requisito de la release del Collector (consulta las notas de la versión), y considera fijar las imágenes por digest. Construye y publica la imagen en CI, y despliégala igual que cualquier imagen oficial: mediante el chart de Helm (image.repository e image.tag) o el Operator (spec.image).

Ten en cuenta que los presets del chart de Helm asumen que ciertos componentes existen. Con una imagen personalizada, configura tú mismo los receivers y processors o confirma que se incluyó cada uno que necesita el preset.

Mantenlo mantenible

• Mantén builder-config.yaml en Git y construye en CI, no en portátiles.
• Reconstruye cuando llegue una nueva release del Collector o un aviso de seguridad afecte a un componente que uses. Renovate o Dependabot pueden vigilar las cadenas de versión.
• Ejecuta components y una prueba de humo con una configuración representativa en CI, para que un componente ausente se detecte antes del despliegue.
• Parte del manifiesto contrib y elimina lo que no uses, en lugar de construir desde cero.