Referencia de configuración YAML del Gateway

Esta referencia cubre la sintaxis YAML para usuarios avanzados que crean configuraciones de puerta de enlace personalizadas. Para obtener información conceptual, consulte Visión general de Gateway. Para una experiencia guiada, utilice la Gateway UI. Si bien se recomienda la Gateway UI para la mayoría de los usuarios, la configuración YAML ofrece un control total sobre la estructura del pipeline de telemetría.

Estructura YAML completa

Las configuraciones del Gateway utilizan un formato YAML declarativo:

version: 2.0.1
autoscaling:
  minReplicas: 6
  maxReplicas: 10
  targetCPUUtilizationPercentage: 60
configuration:
  simplified/v2:
    troubleshooting:
      proxy: false
      requestTraceLogs: false
    steps:
      receivelogs:
        description: Receive logs from OTLP and New Relic proprietary sources
        output:
          - probabilistic_sampler/Logs
      receivemetrics:
        description: Receive metrics from OTLP and New Relic proprietary sources
        output:
          - filter/Metrics
      receivetraces:
        description: Receive traces from OTLP and New Relic proprietary sources
        output:
          - probabilistic_sampler/Traces
      probabilistic_sampler/Logs:
        description: Probabilistic sampling for all logs
        output:
          - filter/Logs
        config:
          rules:
            - name: sample the log records for ruby test service
              description: sample the log records for ruby test service with 70%
              sampling_percentage: 70
              source_of_randomness: trace.id
              conditions:
                - resource.attributes["service.name"] == "ruby-test-service"
          default_sampling_percentage: 100
      probabilistic_sampler/Traces:
        description: Probabilistic sampling for traces
        output:
          - filter/Traces
        config:
          default_sampling_percentage: 100
      filter/Logs:
        description: Apply drop rules and data processing for logs
        output:
          - transform/Logs
        config:
          error_mode: ignore
          rules:
            - name: drop the log records
              description: drop all records which has severity text INFO
              conditions:
                - log.severity_text == "INFO"
              context: log
      filter/Metrics:
        description: Apply drop rules and data processing for metrics
        output:
          - transform/Metrics
        config:
          error_mode: ignore
          rules:
            - name: drop-internal-metrics
              description: drop internal metric
              conditions:
                - IsMatch(name, "^internal\\.")
              context: metric
            - name: drop-debug-datapoints
              description: drop-debug-datapoints
              conditions:
                - attributes["metric.type"] == "debug"
              context: datapoint
      filter/Traces:
        description: Apply drop rules and data processing for traces
        output:
          - transform/Traces
        config:
          error_mode: ignore
          rules:
            - name: drop-health-endpoint
              description: drop-health-endpoint
              conditions:
                - attributes["http.path"] == "/health"
              context: span
            - name: drop-debug-events
              description: drop-debug-events
              conditions:
                - name == "debug_event"
              context: span_event
      transform/Logs:
        description: Transform and process logs
        output:
          - nrexporter/newrelic
        config:
          rules:
            - name: add new field to attribute
              description: for otlp-test-service application add newrelic source type field
              conditions:
                - resource.attributes["service.name"] == "otlp-java-test-service"
              statements:
                - set(resource.attributes["source.type"],"otlp")
      transform/Metrics:
        description: Transform and process metrics
        output:
          - nrexporter/newrelic
        config:
          rules:
            - name: adding a new attributes
              description: adding a new field into a attributes
              conditions:
                - resource.attributes["service.name"] == "payments-api"
              statements:
                - set(resource.attributes["application.name"], "compute-application")
      transform/Traces:
        description: Transform and process traces
        output:
          - nrexporter/newrelic
        config:
          rules:
            - name: remove the attribute
              description: remove the attribute when service name is payment-service
              conditions:
                - resource.attributes["service.name"] == "payment-service"
              statements:
                - delete_key(resource.attributes, "service.version")
      nrexporter/newrelic:
        description: Export to New Relic

Estructura de nivel superior

• version: Versión del formato de configuración (actualmente "2.0.1")
• autoscaling: Configuración de escalado de réplicas de Gateway
• configuration.simplified/v2: Capa de abstracción simplificada para definir pipelines de telemetría
• troubleshooting: Configuración de depuración

Sobrescrituras opcionales

• nrExporterEndpoints: anular los extremos de ingesta predeterminados de New Relic por canalización

configuration:
  simplified/v2:
    troubleshooting: ...
    nrExporterEndpoints:
      nrHost: collector.example.com
      metricsEndpoint: https://metric-api.example.com
      otlpEndpoint: https://otlp.example.com

Jerarquía de configuración

La configuración del gateway sigue una estructura de grafo acíclico dirigido (DAG) donde cada paso define su comportamiento y apunta al siguiente paso en el pipeline usando el campo output. Esto crea un flujo de datos explícito: los datos entran a través de receptores, fluyen a través de procesadores (transformar, filtrar, muestrear) y salen a través de exportadores.

Convenciones de nomenclatura de pasos

• Receptores: receivelogs, receivemetrics, receivetraces

• Procesadores: formato processortype/TelemetryType:

  • Transformar: transform/Logs, transform/Metrics, transform/Traces
  • Filtro: filter/Logs, filter/Metrics, filter/Traces
  • Muestreo: probabilistic_sampler/Logs, probabilistic_sampler/Traces

• Exportadores: nrexporter

Configuraciones del procesador

Gateway admite tres tipos principales de procesadores para transformar, filtrar y muestrear telemetry data. Puede agregar más de un procesador del mismo tipo y colocarlo en cualquier punto del pipeline, de modo que pueda insertar la lógica de procesamiento exactamente donde la necesite, como filtrar datos antes de muestrearlos.

Transformar procesador

Se utiliza para modificar, enriquecer o analizar telemetría mediante OTTL (OpenTelemetry Transformation Language).

Campos de configuración:

• metric_statements: Arreglo para transformaciones de métricas (contexto: métrica)
• log_statements: Arreglo para transformaciones de logs (contexto: log)
• trace_statements: Arreglo para transformaciones de trazas (contexto: span)

Procesador de filtro

Se utiliza para descartar registros de telemetría basados en expresiones booleanas.

Campos de configuración:

• logs: Arreglo de expresiones booleanas de OTTL para el filtrado de logs
• spans: Arreglo de expresiones booleanas OTTL para el filtrado de métricas/trazas

Procesador de muestreo

Se utiliza para implementar la lógica de muestreo probabilístico.

Campos de configuración:

• global_sampling_percentage: Tasa de muestreo predeterminada (0-100)

• conditionalSamplingRules: Arreglo de reglas condicionales

  • nombre: Identificador de regla
  • descripción: Descripción legible por humanos
  • sampling_percentage: Tasa de muestreo para datos coincidentes (0-100)
  • source_of_randomness: Campo a utilizar para la aleatoriedad (típicamente trace.id)
  • condición: Expresión de coincidencia de atributos

Procesador adicional

Se utiliza para insertar un procesador Sample, Filter o Transform adicional en cualquier punto del pipeline. Puede actualizar la configuración YAML agregando un nuevo paso al final, con estos campos:

• <processortype>/<TelemetryType>_<uniqueID> (por ejemplo, transform/Logs_7d7bc):

  • <processortype>: transform, filter o probabilistic_sampler
  • <TelemetryType>: Logs, Metrics o Traces
  • <uniqueID>: una cadena alfanumérica de 5 caracteres. Elija una ID única usted mismo. Debe ser única entre los nombres de los pasos en esta configuración.

• descripción: Una descripción legible por humanos de lo que hace este procesador.

• config: los campos de Config para el tipo de procesador: procesador Transform, procesador Filter o procesador Sampling.

• salida: el nombre del paso que debe recibir datos de este nuevo paso.

Para eliminar un procesador, quite su bloque de paso. Para mantener la continuidad del pipeline, actualice el valor del campo output del paso que lo referenciaba.

Referencia de campos

Campos de nivel superior

Cada campo nrExporterEndpoints es independiente: configure solo los que necesite anular (por ejemplo, solo nrHost), y cualquier campo que omita volverá al extremo de ingesta de New Relic predeterminado de la cuenta.

nrExporterEndpoints los campos se dividen en dos grupos de sobrescritura independientes:

• nrHost, metricsEndpoint, tracesEndpoint, logApiEndpoint, eventApiEndpoint y infraEventApiEndpoint sobrescriben el destino para la telemetría exclusiva de New Relic (agente legacy).
• otlpEndpoint sobrescribe por separado el destino para la telemetría nativa de OTLP. Configurar los campos en un grupo no tiene ningún efecto en el otro.

otlpEndpoint debe ser un host y un esquema básicos (por ejemplo, https://otlp.example.com), sin ningún puerto incluido. Agregar un puerto hace que la configuración no supere la validación y no se guarde.

Campos del paso

Convenciones de nomenclatura de campos

• Use las mayúsculas y minúsculas exactas de los ejemplos (YAML distingue entre mayúsculas y minúsculas).

El arreglo de salida de cada paso especifica el/los siguiente(s) paso(s).

Actualice y despliegue la configuración

1. Haga clic en Clone config para crear un borrador editable de la configuración actual.
2. Edite el YAML según sea necesario.
3. Haga clic en Save draft.
4. Valide la sintaxis con un linter YAML.
5. Despliegue primero en un entorno de no producción.
6. Confirme que la telemetría llegue a New Relic correctamente.
7. Cargue la configuración a través de la UI del gateway.

Recursos adicionales

• https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/ottl/ottlfuncs/README.md
• https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor
• https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor
• https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/probabilisticsamplerprocessor