opentelemetry.html.md.erb

---
title: Configuring the OpenTelemetry Collector
owner: Logging and Metrics
---

You can deploy an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) for <%= vars.app_runtime_abbr %>
to egress traces, metrics, and logs.

When the OpenTelemetry (OTel) Collector is deployed, the Loggregator Forwarder Agent forwards platform and application metrics to the OTel Collector, which then processes traces, metrics, and logs using one or more pipelines that you configure.

# <a id='collector-config'></a> Collector configuration structure


The OTel Collector has a standard YAML-based file format for configuration. 

The structure of <%= vars.app_runtime_abbr %> configuration file consists of three classes of pipeline components that access telemetry data:

* [Exporters](#metric-exporter-config)
* [Receivers](#metric-receiver-config)
* [Processors](#metric-processor-config)

After each pipeline component is configured, add it in the `service.pipelines` [section](#service) of the Collector configuration file.

## <a id='metric-exporter-config'></a> Exporter configuration
For example, to configure the OpenTelemetry Collector to egress metrics using OTLP over gRPC, you can provide the following minimal configuration. This will use the defaults for gRPC and TLS configuration.

```
otlp:
  endpoint: 203.0.113.10:4317
```

As the OTel Collector is deployed on all VMs in Cloud Foundry, you must ensure that all VMs in your deployment are allowed to connect to the OTLP server endpoint.

### <a id='included-exporters'></a> Included exporters
|Exporter | Stability | 
| :--- | :--- | 
| `otlpexporter` | beta | 
| `nopexporter` | beta | 
| `fileexporter` | alpha | 
| `prometheusexporter` | beta | 
| `prometheusremotewriteexporter` | beta | 
| `splunkhecexporter` | beta | 

### <a id='mtls'></a> mTLS

To configure the exporter to use an mTLS connection to the remote OTLP endpoint, you can specify [additional TLS
configuration](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md).

```
otlp:
  endpoint: 203.0.113.10:4317
  tls:
    cert_pem: |
      PEM_ENCODED_CERTIFICATE
    key_pem: |
      PEM_ENCODED_PRIVATE_KEY
    ca_pem: |
      PEM_ENCODED_CERTIFICATE
```

### <a id='multiple-exporters'></a> Multiple exporters

The OTel Collector supports defining multiple exporters, each with its own configuration. For example, you can define two OTLP gRPC exporters that egress metrics to different destinations.

```
otlp:
  endpoint: 203.0.113.10:4317
otlp/another:
  endpoint: 203.0.113.11:4317
```

## <a id='metric-receiver-config'></a> Receiver configuration

Currently, users should not list receivers and include them in the pipeline. By default, receivers are replaced with OTLP receiver that forwarder agent sends to automatically.

## <a id='grpc-compression'></a> gRPC compression

You can configure the type of compression used for OTLP gRPC exporters or receivers. The OTLP gRPC exporter uses `gzip` compression
by default. To reduce CPU usage of the OTel Collector (increasing the size of the payload) you can optionally configure
the OTLP gRPC exporter to use `snappy` compression. Validate that the server you are sending metrics to
support `snappy` compression before making this change.

```
otlp:
  endpoint: 203.0.113.10:4317
  compression: snappy
```

## <a id='metric-processor-config'></a> Processor configuration

Processors are used at various stages of a pipeline to pre-processes data before it is exported. By default, no processors are enabled. The order of the processors in a pipeline determines the order of the processing operations that the Collector applies to the signal. 

Refer to the individual processor [documentation](https://opentelemetry.io/docs/collector/configuration/#processors) for more information.

Currently, the <%= vars.app_runtime_abbr %> distribution of the OpenTelemetry Collector supports the following processors out of the box: `batch`, `memorylimiter`. You can configure processors using the `processors` section of the Collector configuration file.

```
processors:   
  batch:  
```     

### <a id='included-processors'></a> Included processors
| Processor | Stability | 
| :--- | :--- | 
| `batchprocessor` | beta | 
| `memorylimiterprocessor` | beta | 
| `transformprocessor` | alpha | 
| `filterprocessor` | alpha |

## <a id='authentication'></a> Authentication

The <%= vars.app_runtime_abbr %> distribution of the OpenTelemetry Collector does not currently include any authenticator extensions. Please let us know in the [Cloud Foundry Slack](#logging-and-metrics) `#logging-and-metrics` channel if there are authenticator extensions you would find useful.

## <a id='available-exporters'></a> Reviewing the available components

The <%= vars.app_runtime_abbr %> distribution of the OpenTelemetry Collector ships with a number of components. To see
the components that are available for use, run the following command on a VM that has otel-collector deployed.

```
/var/vcap/packages/otel-collector/otel-collector components
```

## <a id='service'></a> Service section
The  `service`  section is used to configure what components are enabled in the Collector based on the configuration found in the receivers, processors, exporters, and extensions sections. If a component is configured, but not defined referenced the  `service`  section, then it’s not enabled.

The service section consists of two subsections:
* [Extensions](#extensions)
* [Pipelines](#pipelines)

### <a id='extensions'></a> Extensions

You can enable desired extensions using `extensions` subsections:

```
service:
  extensions: [pprof, health_check, zpages]
```

### <a id='pipelines'></a> Pipelines

A pipeline is a set of components used to process a signal. Before including a receiver, processor, or exporter in a pipeline, make sure to define its configuration in the appropriate section.

You can use the same receiver, processor, or exporter in more than one pipeline. When a processor is referenced in multiple pipelines, each pipeline gets a separate instance of the processor.

The following is an example of pipeline configuration. Note that the order of processors dictates the order in which data is processed:

```
service:
  extensions: [pprof]
  pipelines:  
    traces:
    receivers: [otlp/test]
    processors: [batch]
    exporters: [otlp]
    metrics:       
    receivers: [otlp/test]
    processors: [batch]
    exporters: [otlp]
```

## <a id='example-config'></a> Example config
Below is an example config structure:
```
receivers:
  otlp/test:     
  protocols:
    grpc: 

processors:   
  batch: 

exporters:
  otlp:
    endpoint: otelcol:4317

extensions:
  pprof: 

service:
  extensions: [pprof]
  pipelines:  
    traces:
      receivers: [otlp/test]
      processors: [batch]
      exporters: [otlp]
    metrics:       
      receivers: [otlp/test]
      processors: [batch]
      exporters: [otlp]
```

## <a id='deploying'></a> Deploying the OpenTelemetry Collector

<% if vars.platform_code == 'CF' %>
CF Deployment provides [experimental operations files](https://github.com/cloudfoundry/cf-deployment/tree/main/operations/experimental)
that you can use to deploy the OTel Collector:

* [on Linux](https://github.com/cloudfoundry/cf-deployment/blob/main/operations/experimental/add-otel-collector.yml)
* [on Windows](https://github.com/cloudfoundry/cf-deployment/blob/main/operations/experimental/add-otel-collector-windows.yml)

For example, to deploy a fresh CF Deployment with OTel Collector enabled, run:

```
bosh deploy cf-deployment.yml \
  --ops-file=operations/experimental/add-otel-collector.yml \
  --var-file=otel_collector_metric_exporters=YOUR_METRIC_EXPORTER_CONFIG_FILE_PATH.yml \
  --var=system_domain=YOUR_SYSTEM_DOMAIN
```
<% else %>
  <%= partial "/pcf/core/deploy_otel_collector" %>
<% end %>