Beta Disclaimer

This documentation mentions a product that is currently beta. AppDynamics reserves the right to change the product at any time before making it generally available as well as never making it generally available. Any buying decisions should be made based on features and products that are currently generally available. Please speak to your account representative if you are interested in participating in the beta, or in being notified when the feature becomes generally available.

OpenTelemetry is a single, standardized vendor-agnostic solution used to generate, collect, and export telemetry data. Telemetry data consists of traces, metrics, and logs. OpenTelemetry uses a set of APIs and SDKs to function as a pipeline to ingest and distribute data.

AppDynamics provides an OpenTelemetry Protocol compliant backend to ingest OpenTelemetry trace data generated from applications monitored using OpenTelemetry components. The ingested data is processed by the AppDynamics backend to provide monitoring and alerting capabilities in your application and cloud environments. This page describes how to configure AppDynamics and OpenTelemetry to send OpenTelemetry trace data to the AppDynamics backend.

Review AppDynamics and OpenTelemetry Requirements

AppDynamics

OpenTelemetry is not available for on-premises Controllers.

  • To use AppDynamics OpenTelemetry, you need a SaaS Controller version >= 21.2.0.
  • Active AppDynamics Pro edition license.
  • API Key to authenticate with AppDynamics backend.

Users must have a role defined with the View and Configure Licenses permission for license management activity.

  • To view your current AppDynamics build version in the Controller UI, go to About AppDynamics.
  • To view your current AppDynamics edition in the Controller UI, go to License.
  • To obtain your AppDynamics API Key, work closely with your account representative. To learn more, see x-api-key in the Attributes Description section.

OpenTelemetry

  • Ensure that you have OpenTelemetry Collector >= 0.14.0 downloaded and installed on your deployment. See the OpenTelemetry Collector Getting Started documentation.
  • Verify that the OpenTelemetry Collector can connect and report traces to the AppDynamics backend.

Configure the OpenTelemetry Collector YAML File

To send the distributed traces to the AppDynamics backend, you must configure the OpenTelemetry Collector YAML file.

  1. Install the OpenTelemetry Collector
  2. Configure Your Applications to Send Service Resource Attributes. 

  3. Configure the OpenTelemetry Collector for AppDynamics. 

  4. Verify Configuration. 

Install the OpenTelemetry Collector

Install the OpenTelemetry Collector in your computing environment. The OpenTelemetry Collector acts as the receiver in your pipeline and gathers telemetry data from various applications.

Configure Your Applications to Send Service Resource Attributes

AppDynamics relies on the service.name and service.namespace trace resource attributes to map the services to AppDynamics tiers and applications, respectively.

  • service.name: Your AppDynamics tier name. Set the corresponding service.name resource attribute for every service being monitored.
  • service.namespace: Your AppDynamics application name. Set the corresponding service.namespace trace resource attribute for every application being monitored. 

You can set these service.name and service.namespace attributes using the OTEL_RESOURCE_ATTRIBUTES environment variable, or from inside your application code. Please consult the appropriate OpenTelemetry language-specific documentation for your code.

Configure OpenTelemetry Collector for AppDynamics

By default, the OpenTelemetry Collector enables and accepts OTLP (OpenTelemetry Protocol) trace data and sends it to the AppDynamics backend using the default configuration through the OTLP HTTP Exporter.

To configure your OpenTelemetry collector to report data to your AppDynamics Controller, edit your otel-config.yml configuration file using this information:

  • Processors: (Resource and Batch): Convert data into chosen formats.
  • Receivers: Send data to the OpenTelemetry Collector.
  • Exporters: Send the converted data to the desired locations.
  • Service: Ensures that all previously noted exporters, receivers, and processors are included in the service pipeline.
  • Attributes Description: Sets the trace attributes for every service being monitored.

Processors

Resource

Use the resource processor to add the AppDynamics Controller account, host, and port.

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

Resource Processor

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
YML
Batch

Use the batch processor to improve performance. The batch setting accumulates data received through the OpenTelemetry Observability Collector pipeline and sends it to the backend efficiently. The 'batch' setting defaults the collection and processing to a timeout of 30 seconds, or when a batch size of 8,192 is reached.

  • timeout: Time duration 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.

Batch Processor

processors:
  batch:
    timeout: 30s
    send_batch_size: 8192
YML

Receivers

Receivers use OTLP to support transaction-oriented application data processing. For more information, see OpenTelemetry's OTLP Receiver documentation.

Specify your receivers endpoints:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: localhost:55680
      http:
        endpoint: localhost:55681
YML

Exporters

Use the OTLP HTTP Exporter to send data, including the <x-api-key> in the header, to the AppDynamics endpoint <appd-endpoint>. To learn more, see <appd-endpoint> in the Attributes Description section. To obtain your <x-api-key>, work closely with your AppDynamics account representative.

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

Service

Ensure that all previously noted exporters, receivers, and processors are included in the service pipeline:

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

Attributes Description

KeyLocationTypeExampleRequiredDescription
appd-endpoint

otlphttp exporter


string
  • Asia Pacific (Sydney): https://syd-sls-agent-api.saas.appdynamics.com/
  • EU (Frankfurt): https://fra-sls-agent-api.saas.appdynamics.com/
  • US West (Oregon): https://pdx-sls-agent-api.saas.appdynamics.com/
YesYour AppDynamics endpoint where the OpenTelemetry Collector sends the ingested traces. AppDynamics endpoints are available in the following regions: Sydney, Frankfurt, and Oregon.
x-api-keyotlphttp exporterstring<alpha numeric key>
YesYour AppDynamics API key must be defined as an HTTP header. [1]
appdynamics.controller.accountresource attributestringacmeYesAppDynamics Controller account name.
appdynamics.controller.hostresource attributestringacme.saas.appdynamics.comYes

AppDynamics Controller host used by OpenTelemetry.

Do not include http:// or https://.

appdynamics.controller.portresource attributeinteger443YesAppDynamics Controller port number.
service.nameresource attributestringshoppingcartYesLogical name of the service; equivalent to your AppDynamics tier name. Set the corresponding service.name trace resource attribute for every service being monitored using either the SDK, or by setting the OTEL_RESOURCE_ATTRIBUTES environment variable. [2]
service.namespaceresource attributestringShop
YesA namespace for the service.name; equivalent to your AppDynamics application name. Set corresponding service.namespace trace resource attribute for every service being monitored using either the SDK, or by setting the OTEL_RESOURCE_ATTRIBUTES environment variable. [3]

[1]: To obtain your unique x-api-key, you should work closely with your AppDynamics account team.
[2]: MUST be the same for all instances of horizontally scaled services.
[3]: A non-null, non-empty string value for service.namespace is required.

AppDynamics Configuration File Example

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
  batch:
    timeout: 30s
    send_batch_size: 8192
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: localhost:55680
      http:
        endpoint: localhost:55681
exporters:
  otlphttp:
    endpoint: "https://pdx-sls-agent-api.saas.appdynamics.com"
    headers: {"x-api-key": "****************"}
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlphttp]
YML

Verify Configuration

To validate that your configuration is working properly, review your OpenTelemetry Collector logs.

Visualize Your OpenTelemetry Data

AppDynamics Open Telemetry ingests and aggregates traces into Business Transaction flow metrics. A trace represents an end-to-end request which can be made up of single or multiple spans. Each span represents a single event within a component in the application triggered in the trace. The Business Transaction represents the entire graph of all traces sharing an origin span, and shows how these related traces flow between services.

Flow maps are a dynamic visual representation of your monitored environment's components and activities. Services monitored using OpenTelemetry are represented by the OpenTelemetry icon in the AppDynamics User Interface.

To view your OpenTelemetry data:

  1. Select the OpenTelemetry-enabled Controller.
  2. Navigate to the application name that you specified with the service.namespace resource attribute value.
  3. Select Application Dashboard > Dashboard > Application Flow Map.

This example shows an application with OpenTelemetry enabled.

Application Flow Map

This example application consists of six tiers: alpha, beta, charlie, delta, echojava-service. Next to each tier icon, a telescope icon displays. These telescope icons indicate that OpenTelemetry is successfully enabled for the tiers listed. 

Under Applications > Tiers & Nodes, the tiers represent the services (defined by service.name) encountered by the ingested traces.

The Applications > Business Transactions view displays the Business Transactions. The names of the Business Transactions are derived from the name of the first span of each trace (also known as the root span). In this example, the first span is reported from the alpha tier and is named /alpha/<username>. The health status, response time, number of calls, and additional Business Transaction metrics are reported for the Business Transaction.

Business Transactions

The AppDynamics Flow Map supports these programming language icons: C++, C#, Elixir, Erlang, Go, Java, JavaScript, Python, and Rust.
C++ and C# p
rogramming languages default to a .NET icon in the Flow Map.

Our exit calls support generic database calls, and messaging queues that are represented as Kafka for Beta.


Troubleshooting

Flow Map 

If you do not see the Flow Map in the Controller, review your configuration procedure. If the issue persists, please work with AppDynamics Support.