Configure the OpenTelemetry™ Collector

The OpenTelemetry Collector acts as the service pipeline by gathering telemetry data from your applications and exporting it to a backend. With AppDynamics for OpenTelemetry, the OpenTelemetry Collector collects and sends distributed traces to the AppDynamics backend.

The Collector consists of three components:

• Receivers: Receives data from OpenTelemetry sources (tracers and SDKs)
• Processors: Allows additional processing of data, such as data enrichment and batching
• Exporters: Converts the data into a specified format and sends the converted data to a chosen destination

See the sections below to configure these components in your OpenTelemetry otel-config.yaml file. Once configured, the components must be enabled via pipelines in the service section.

Before You Begin

To get started with AppDynamics for OpenTelemetry:

1. Deploy the OpenTelemetry Collector version >= 0.36.0 in your computing environment.
2. In the Controller top navigation panel, click OTel > Get Started.
3. Click Generate Access Key. 

   If you have already completed onboarding, you can retrieve the API Key in the Controller:

   1. In the top navigation panel, click OTel.
   2. Under the Access Key section, click Show.
   3. Copy the key to use in the Configure Exporters section below.

Configure Receivers

Receivers specify how data gets into the OpenTelemetry Collector. Receivers use OTLP to support transaction-oriented application data processing.

We recommend you use OpenTelemetry Protocol (OTLP) version >= 0.9.0 as the specified trace receiver. For a list of verified OTLP open-source versions, see Verified Open Source Versions.

In the receivers: OTLP: section, specify the Collector endpoints:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint:
      http:
        endpoint:

Configure Processors

Processors allow additional processing of data, such as data enrichment and batching.

You must configure the processors section to add AppDynamics Controller information and (optional) custom data collection.

Resource Processor

Add the AppDynamics Controller account, host, and port to the resource processor:

In the resource: attributes: section, add the following:

• appdynamics.controller.account: Your AppDynamics Controller account name
• appdynamics.controller.host: Your AppDynamics Controller hostname
• appdynamics.controller.port: Your AppDynamics Controller port number

You also must add service.name and service.namespace resource attributes, but you have three options for how to add them:

• Set the service.name and service.namespace from inside your application code.
• Set service.name in your OpenTelemetry otel-config.yaml file.
• Set service.name and service.namespace in the OTEL_RESOURCE_ATTRIBUTES environment variable.

See Configure Resource Attributes for more information.

processors:
  resource:
    attributes:
  	- key: appdynamics.controller.account
      action: upsert
      value: "acme"
  	- key: appdynamics.controller.host
      action: upsert
      value: "acme.saas.appdynamics.com"
  	- key: appdynamics.controller.port
      action: upsert
      value: 443 # value must be an integer.

Batch Processor

The batch processor accepts spans, metrics, or logs and places them into batches in the OpenTelemetry Collector pipeline.

Configure the following batch: attributes to help improve performance:

• timeout: Time after which a batch is sent, regardless of size. The default is 30 seconds.

• send_batch_size: Number of spans or metrics after which a batch is sent. The default is 8,192.

  

  We recommend batching 90 spans or less per request for optimal results.

processors:
  batch:
    timeout: 30s
    send_batch_size: 90

Configure Exporters

The exporter is how data is sent to the AppDynamics backend. For AppDynamics for OpenTelemetry, only HTTP is supported to transmit OTLP trace export calls. Your tracer/SDKs exporter should be based on OTLP version >= 0.9.0.

In the exporters: otlphttp: section, you must configure the following attributes with the AppDynamics endpoint and API key:

exporters:
  otlphttp:
    endpoint: "<appd-endpoint>"
    headers: {"x-api-key": "<x-api-key>"}

For more details on <x-api-key> and <appd-endpoint> see Resource Attribute Descriptions.

For more details on <appd-endpoint> see Regions and Endpoints.

Configure the Service Pipeline

The service pipeline is what enables the configurations set in the receivers: , processors: , and exporters: sections.

You must verify that all previously noted exporters, receivers, and processors are included in the service: pipelines: section:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlphttp]

Regions and Endpoints

Please note that your OpenTelemetry data may transit through regions different from where your Controller is hosted if you configure your OpenTelemetry Collector using an AppDynamics endpoint located outside of the region where your Controller is hosted.

Attribute Descriptions

Key	Location	Type	Example	Required	Description
appd-endpoint	otlphttp exporter	string	See Supported Regions.	Yes	Your AppDynamics endpoint for your region where the OpenTelemetry Collector sends the ingested traces.
x-api-key	otlphttp exporter	string	<alpha numeric key>	Yes	Your AppDynamics API key must be defined as an HTTP header. To obtain your unique x-api-key, you should work closely with your AppDynamics account team.
appdynamics.controller.account	resource attribute	string	acme	Yes	AppDynamics Controller account name.
appdynamics.controller.host	resource attribute	string	acme.saas.appdynamics.com	Yes	AppDynamics Controller host used by OpenTelemetry. Do not include http:// or https://.
appdynamics.controller.port	resource attribute	integer	443	Yes	AppDynamics Controller port number.
service.name	resource attribute	string	shoppingcart	Yes	Logical name of the service; equivalent to your AppDynamics tier name. Set the corresponding service.name resource attribute for every service being monitored using either the SDK, or by setting the OTEL_RESOURCE_ATTRIBUTES environment variable. Must be the same for all instances of horizontally scaled services.
service.namespace	resource attribute	string	Shop	Yes	A namespace for the service.name; equivalent to your AppDynamics application name. Set the corresponding service.namespace  resource attribute for every service being monitored using either the SDK, or by setting the OTEL_RESOURCE_ATTRIBUTES environment variable. A non-null, non-empty string value for service.namespace is required.

Collector Configuration Sample

This example includes configuration for the processors, receivers, exporters, service, and attributes:

processors:
  resource:
    attributes:
    - key: appdynamics.controller.account
      action: upsert
      value: "acme"
    - key: appdynamics.controller.host
      action: upsert
      value: "acme.saas.appdynamics.com"
    - key: appdynamics.controller.port
      action: upsert
      value: 443
	- key: service.namespace
      action: upsert		
	  value: shop
	batch:
		timeout: 30s
		send_batch_size: 90
receivers:
  otlp:
    protocols:
      grpc:
        endpoint:
      http:
        endpoint:
exporters:
  otlphttp:
    endpoint: "https://<your region>-sls-agent-api.saas.appdynamics.com" // See the Supported Regions section above.
    headers: {"x-api-key": "****************"}
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlphttp]

Verify Configuration

To validate that your configuration is working properly, review your OpenTelemetry Collector logs. The output from the console log should not have any errors.

You can also set up a logging exporter to monitor the Collector. See Logging Exporter for more information.

Next Steps

After deploying and configuring the OpenTelemetry Collector, you must Configure Resource Attributes.

OpenTelemetry™ is a trademark of The Linux Foundation®.