--- title: Gateway YAML configuration reference source: https://docs.newrelic.com/docs/new-relic-control/pipeline-control/gateway/yaml-overview --- This reference covers YAML syntax for advanced users creating custom gateway configurations. For conceptual information, see [Gateway overview](https://docs.newrelic.com/docs/new-relic-control/pipeline-control/gateway/overview). For a guided experience, use the [Gateway UI](https://docs.newrelic.com/docs/new-relic-control/pipeline-control/gateway/ui-guide). While the Gateway UI is recommended for most users, YAML configuration offers full control over the telemetry pipeline structure. ## Complete YAML structure Gateway configurations use a declarative YAML format: ```yaml 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 ``` > #### 💡 TIP > > **Installation mode note:** The `version` and `autoscaling` fields behavior depends on your fleet's installation mode: > > - **With Flux:** These fields are fully managed through the UI. Changes deploy automatically to all clusters in the fleet. > - **Without Flux:** These fields can be set during initial installation to configure the Horizontal Pod Autoscaler (HPA). However, post-installation changes via the UI are ignored. Only the `configuration.simplified/v2` section (pipeline rules) continues to deploy automatically via `ConfigMap`. You must manually update scaling via HPA and versions via Helm upgrades. Refer to [Manage gateway without Flux](https://docs.newrelic.com/docs/new-relic-control/pipeline-control/gateway/install-gateway-without-flux#manage-gateway-after-installation) for details. ### Top-level structure - `version`: Configuration format version (currently `"2.0.1"`) - `autoscaling`: Gateway replica scaling configuration - `configuration.simplified/v2`: Simplified abstraction layer for defining telemetry pipelines - `troubleshooting`: Debug settings ### Optional overrides - `nrExporterEndpoints`: Override the default New Relic ingest endpoints per pipeline ```yaml configuration: simplified/v2: troubleshooting: ... nrExporterEndpoints: nrHost: collector.example.com metricsEndpoint: https://metric-api.example.com otlpEndpoint: https://otlp.example.com ``` ## Configuration hierarchy The gateway configuration follows a directed acyclic graph (DAG) structure where each step defines its behavior and points to the next step in the pipeline using the output field. This creates an explicit data flow: data enters through receivers, flows through processors (transform, filter, sample), and exits through exporters. ### Step naming conventions - Receivers: `receivelogs`, `receivemetrics`, `receivetraces` - Processors: `processortype/TelemetryType` format: - Transform: `transform/Logs`, `transform/Metrics`, `transform/Traces` - Filter: `filter/Logs`, `filter/Metrics`, `filter/Traces` - Sampling: `probabilistic_sampler/Logs`, `probabilistic_sampler/Traces` - Exporters: `nrexporter` ### Processor configurations Gateway supports three primary processor types for transforming, filtering, and sampling telemetry data. #### Transform processor Used for modifying, enriching, or parsing telemetry using OTTL (OpenTelemetry Transformation Language). Config fields: - metric_statements: Array for metric transformations (context: metric) - log_statements: Array for log transformations (context: log) - trace_statements: Array for trace transformations (context: span) #### Filter processor Used to drop telemetry records based on boolean expressions. Config fields: - logs: Array of OTTL boolean expressions for log filtering - spans: Array of OTTL boolean expressions for metric/trace filtering #### Sampling processor Used to implement probabilistic sampling logic. Config fields: - global_sampling_percentage: Default sampling rate (0-100) - conditionalSamplingRules: Array of conditional rules - name: Rule identifier - description: Human-readable description - sampling_percentage: Sampling rate for matched data (0-100) - source_of_randomness: Field to use for randomness (typically trace.id) - condition: Attribute matching expression ## Field reference ### Top-level fields | Field | Type | Required | Default | | ------------------------------------------ | ------- | -------- | ------- | | version | string | Yes | - | | autoscaling.minReplicas | integer | No | 6 | | autoscaling.maxReplicas | integer | No | 10 | | autoscaling.targetCPUUtilizationPercentage | integer | No | 60 | | configuration.simplified/v2 | object | Yes | - | | troubleshooting.proxy | boolean | No | false | | troubleshooting.requestTraceLogs | boolean | No | false | | nrExporterEndpoints.nrHost | string | No | - | | nrExporterEndpoints.metricsEndpoint | string | No | - | | nrExporterEndpoints.tracesEndpoint | string | No | - | | nrExporterEndpoints.logApiEndpoint | string | No | - | | nrExporterEndpoints.eventApiEndpoint | string | No | - | | nrExporterEndpoints.infraEventApiEndpoint | string | No | - | | nrExporterEndpoints.otlpEndpoint | string | No | - | Each `nrExporterEndpoints` field is independent: set only the ones you need to override (for example, just `nrHost`), and any field you omit falls back to the account's default New Relic ingest endpoint. `nrExporterEndpoints` fields fall into two independent override groups: - `nrHost`, `metricsEndpoint`, `tracesEndpoint`, `logApiEndpoint`, `eventApiEndpoint`, and `infraEventApiEndpoint` override the destination for New Relic-proprietary (legacy agent) telemetry. - `otlpEndpoint` separately overrides the destination for OTLP-native telemetry. Setting fields in one group has no effect on the other. `otlpEndpoint` must be a bare host and scheme (for example, `https://otlp.example.com`), with no port included. Adding a port causes the configuration to fail validation and not save. > #### 💡 TIP > > **Installation mode note:** The `version` and `autoscaling` fields behavior depends on your fleet's installation mode: > > - **With Flux:** These fields are fully managed through the UI. Changes deploy automatically to all clusters in the fleet. > - **Without Flux:** These fields can be set during initial installation to configure the Horizontal Pod Autoscaler (HPA). However, post-installation changes via the UI are ignored. Only the `configuration.simplified/v2` section (pipeline rules) continues to deploy automatically via `ConfigMap`. You must manually update scaling via HPA and versions via Helm upgrades. Refer to [Manage gateway without Flux](https://docs.newrelic.com/docs/new-relic-control/pipeline-control/gateway/install-gateway-without-flux#manage-gateway-after-installation) for details. ### Step fields | Field | Type | Required | Description | | ----------- | ------ | ----------- | ----------------------------------------------------- | | description | string | Recommended | Human-readable description | | config | object | Conditional | Required for processors, omit for receivers/exporters | | output | array | Yes | Next step names (empty \[] for exporters) | ## Field naming conventions - Use exact casing from examples (YAML is case-sensitive). Each step's output array specifies the next step(s). ## Validation and deployment 1. Validate syntax with an YAML linter. 2. Deploy to non-production environment first. 3. Confirm telemetry reaches New Relic correctly. 4. Upload configuration through the gateway UI. ## Additional resources - - - -