--- 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. You can add more than one processor of the same type and place it at any point in the pipeline, so you can insert processing logic exactly where you need it, such as filtering data before it's sampled. #### 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 #### Additional processor Used to insert an extra Sample, Filter, or Transform processor at any point in the pipeline. You can [update the YAML config](#update-and-deploy-your-configuration) by adding a new step at the end, with these fields: - `/_` (for example, `transform/Logs_7d7bc`): - ``: `transform`, `filter`, or `probabilistic_sampler` - ``: `Logs`, `Metrics`, or `Traces` - ``: A 5-character alphanumeric string. Choose a unique ID yourself. It must be unique among the step names in this config. - description: A human-readable description of what this processor does. - config: The Config fields for the processor type: [Transform processor](#transform-processor), [Filter processor](#filter-processor), or [Sampling processor](#sampling-processor). - output: The name of the step that should receive data from this new step. To delete a processor, remove its step block. To maintain the continuity of the pipeline, update the `output` field value of the step that referenced it. > #### 💡 TIP > > A step's position within the YAML file doesn't matter. The `output` field definitions are what maintain the pipeline's order. ## 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). ## Update and deploy your configuration 1. Click **Clone config** to create an editable draft of the current configuration. 2. Edit the YAML as needed. 3. Click **Save draft**. 4. Validate syntax with a YAML linter. 5. Deploy to a non-production environment first. 6. Confirm telemetry reaches New Relic correctly. 7. Upload the configuration through the gateway UI. ## Additional resources - - - -