Loading

Central configuration for EDOT SDKs

Stack Preview 9.1.0 ECH Preview 9.1.0 Serverless Unavailable

Manage Elastic Distribution of OpenTelemetry (EDOT) SDKs through the APM Agent Central Configuration feature in the Applications UI. Changes are automatically propagated to the deployed EDOT SDKs. Refer to APM Agent Central Configuration for more information.

This feature implements the Open Agent Management Protocol (OpAMP). Refer to Open Agent Management Protocol for more information.

To use APM Agent Central Configuration for EDOT SDKs, you need:

  • An Elastic self-managed or Elastic Cloud deployment, version 9.1 or higher.
  • A standalone EDOT Collector, in either Agent or Collector mode.
  • EDOT SDKs instrumenting your application.

The following versions of EDOT and Elastic Stack support central configuration:

Component Minimum version
Kibana 9.1 or higher
EDOT Collector 8.19, 9.1 or higher
EDOT Android 1.2.0 or higher
EDOT Java 1.5.0 or higher
EDOT Node.js 1.2.0 or higher
EDOT PHP 1.1.1 or higher
EDOT Python 1.4.0 or higher
Note

Serverless deployments are not currently supported.

To activate APM Agent Central Configuration for EDOT SDKs, follow these steps.

  1. Retrieve your credentials

    You need a valid Elasticsearch API key to authenticate to the Elasticsearch endpoint.

    Retrieve your Elasticsearch URL and your API key:

    1. Retrieve the Elasticsearch URL for your Elastic Cloud deployment:

      1. Go to the Elastic Cloud console.
      2. Next to your deployment, select Manage.
      3. Under Applications next to Elasticsearch, select Copy endpoint.

    2. Create an API Key following these instructions.

    Make sure the API key has config_agent:read permissions and resources set to -.

    Example JSON payload 
    POST /_security/api_key
{
  "name": "apmconfig-opamp-test-sdk",
  "metadata": {
    "application": "apm"
  },
  "role_descriptors": {
    "apm": {
      "cluster": [],
      "indices": [],
      "applications": [
        {
          "application": "apm",
          "privileges": [
            "config_agent:read"
          ],
          "resources": [
            "*"
          ]
        }
      ],
      "run_as": [],
      "metadata": {}
    }
  }
}

  2. Edit the EDOT Collector configuration

    Edit the EDOT Collector configuration to activate the central configuration feature:

    extensions:
  bearertokenauth:
    scheme: "APIKey"
    token: "<ENCODED_ELASTICSEARCH_APIKEY>"

  apmconfig:
    opamp:
      protocols:
        http:
          # Default is localhost:4320
          # endpoint: "<CUSTOM_OPAMP_ENDPOINT>"
    source:
      elasticsearch:
        endpoint: "<ELASTICSEARCH_ENDPOINT>"
        auth:
          authenticator: bearertokenauth

    Restart the Elastic Agent to also restart the Collector and apply the changes.

    Note

    Refer to Secure connection if you need to secure the connection between the EDOT Collector and Elastic using TLS or mutual TLS.

  3. Set the environment variable for the SDKs

    Activate the central configuration feature in the SDKs by setting the ELASTIC_OTEL_OPAMP_ENDPOINT environment variable to the URL endpoint of the apmconfig extension that you configured in the previous step. For example:

    export ELASTIC_OTEL_OPAMP_ENDPOINT="http://localhost:4320/v1/opamp"

    Restart the instrumented application to apply the changes.

    Note

    Central configuration uses the service.name and deployment.environment.name OpenTelemetry resource attributes to target specific instances with a configuration. If no environment is specified, the central configuration feature will match All as the environment.

  4. Check that the EDOT SDK shows up

    Wait some time for the EDOT SDK to appear in Kibana under Agent Configuration.

    1. Go to Kibana → Observability → Applications and select a service.
    2. Select Settings and go to Agent Configuration.
    Note

    Your application must produce and send telemetry data for the EDOT SDK to appear in Agent Configuration. This is because central configuration requires an application name as the key, which can't be defined until the application name is associated with the EDOT SDK agent after receiveing telemetry.

For a list of settings that you can configure through APM Agent Central Configuration, refer to the configuration reference of each EDOT SDK:

EDOT iOS currently supports APM Agent Central Configuration through APM Server. Refer to EDOT iOS configuration for more details.

To deactivate central configuration, remove the ELASTIC_OTEL_OPAMP_ENDPOINT environment variable.

Restart the instrumented application to apply the changes.