Uso dos SDKs do AWS Distro para OpenTelemetry (ADOT) para a exportação de rastreamentos sem a necessidade de um coletor - Amazon CloudWatch
Pré-requisitoDefinir permissões do IAM para o Amazon EC2Configurar permissões do IAM para hosts on-premisesHabilitação dos SDKs do ADOT

Uso dos SDKs do AWS Distro para OpenTelemetry (ADOT) para a exportação de rastreamentos sem a necessidade de um coletor

É possível usar os SDKs do ADOT para dispensar o uso do coletor e transmitir os rastreamentos diretamente ao endpoint do OTLP (destinado a rastreamentos).

nota

Por padrão, o Application Signals é habilitado quando você habilita a Pesquisa de transações. O Application Signals não é compatível com o AWS Distro para OpenTelemetry e deve ser desabilitado.

Pré-requisito

Certifique-se de que a Pesquisa de transações esteja habilitada para enviar spans para o endpoint do OTLP do X-Ray. Para obter mais informações, consulte Conceitos básicos da Pesquisa de transações.

Definir permissões do IAM para o Amazon EC2

Siga estas etapas para anexar a política AWSXrayWriteOnlyPolicy do IAM ao perfil do IAM da instância do Amazon EC2:

  1. Abra o console do CloudWatch, em https://console.aws.amazon.com/cloudwatch/.

  2. Escolha Perfis e localize e selecione o perfil usado pela instância do Amazon EC2.

  3. Na guia Permissões, escolha Adicionar permissões e, em seguida, Anexar políticas.

  4. Usando a caixa de pesquisa, pesquise a política AWSXrayWriteOnlyPolicy.

  5. Selecione a política AWSXrayWriteOnlyPolicy e escolha Adicionar permissões.

Configurar permissões do IAM para hosts on-premises

Siga as etapas a seguir para criar o usuário do IAM a ser usado para fornecer permissões aos hosts on-premises.

  1. Abra o console do CloudWatch, em https://console.aws.amazon.com/cloudwatch/.

  2. Escolha Usuários e, em seguida, Criar usuário.

  3. Escolha Usuários, Criar usuário.

  4. Em Detalhes do usuário, em Nome do usuário, insira um nome para o novo usuário do IAM. Esse é o nome de login para a AWS que será usado para autenticar seu host.

  5. Escolha Próximo.

  6. Na página Definir permissões, em Opções de permissões, escolha Anexar políticas diretamente.

  7. Na lista de Políticas de permissões, selecione a política AWSXrayWriteOnlyPolicy para adicionar ao usuário.

  8. Escolha Próximo.

  9. Na página Revisar e criar, certifique-se de que o nome de usuário seja satisfatório e que a política AWSXrayWriteOnlyPolicy esteja no Resumo de permissões.

  10. Selecione Criar usuário.

  11. Crie e recupere sua chave de acesso da AWS e uma chave secreta:

    1. No painel de navegação do console do IAM, escolha Usuários e depois selecione o nome do usuário do usuário que você criou na etapa anterior.

    2. Na página do usuário, escolha a guia Credenciais de segurança.

    3. Na seção Chaves de acesso, escolha Criar chave de acesso.

    4. Em Criar chave de acesso: etapa 1, escolha Command Line Interface (CLI).

    5. Em Criar chave de acesso: etapa 2, insira uma tag opcional e escolha Próximo.

    6. Em Criar chave de acesso: etapa 3, selecione Baixar arquivo .csv para salvar um arquivo .csv com a chave de acesso e a chave de acesso secreta do usuário do IAM. Você precisará dessas informações para as próximas etapas.

    7. Selecione Concluído.

  12. Configure suas credenciais da AWS no host on-premises ao inserir o comando a seguir. Substitua ACCESS_KEY_ID e SECRET_ACCESS_ID pela chave de acesso recém-gerada e pela chave de acesso secreta do arquivo .csv que você baixou na etapa anterior.

    $ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json

Habilitação dos SDKs do ADOT

É possível habilitar o envio de rastreamentos da sua aplicação diretamente para o endpoint do OTLP por meio do SDK do AWS Distro para OpenTelemetry (ADOT) em Java, Node.js, Python e .NET.

Java

  1. Faça download da versão mais recente do agente de instrumentação automática em Java do AWS Distro para OpenTelemetry. Você pode baixar a versão mais recente ao usar este comando:

    curl -L -O https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar

    Para visualizar todas as versões lançadas, consulte as versões do aws-otel-java-instrumentation.

  2. Para habilitar o exportador que envia rastreamentos diretamente para o endpoint de rastreamentos do OTLP do X-Ray e para otimizar os benefícios, use as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação.

  3. Para a variável OTEL_RESOURCE_ATTRIBUTES, especifique as seguintes informações como pares de chave/valor:

    (Opcional) service.name define o nome do serviço. Isso será exibido como o nome do serviço para a aplicação nos painéis do Application Signals. Quando você não fornecer um valor para essa chave, o padrão de UnknownService será usado.

    (Opcional) deployment.environment define o ambiente em que a aplicação é executada. Essa variável será exibida como o ambiente Hospedado em da aplicação. Quando você não especificar isso, um dos seguintes padrões será usado:

    • Se for uma instância que faz parte de um grupo do Auto Scaling, ela será definida como ec2:name-of-Auto-Scaling-group.

    • Se for uma instância do Amazon EC2 que não faz parte de um grupo do Auto Scaling, ela será definida como ec2:default.

    • Se for um host on-premises, ele será definido como generic:default.

    Essa variável de ambiente é usada somente pelo Application Signals e é convertida em anotações de rastreamentos do X-Ray e em dimensões de métricas do CloudWatch.

  4. Para a variável OTEL_EXPORTER_OTLP_TRACES_ENDPOINT , especifique o endpoint de rastreamentos do OTLP do X-Ray: https://xray.[AWSRegion].amazonaws.com/v1/traces. Por exemplo:

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. Para a variável JAVA_TOOL_OPTIONS, especifique o caminho no qual o agente de instrumentação automática em Java do AWS Distro para OpenTelemetry está armazenado.

    export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"

    Por exemplo:

    export AWS_ADOT_JAVA_INSTRUMENTATION_PATH="./aws-opentelemetry-agent.jar"

  6. Para a variável OTEL_METRICS_EXPORTER, é recomendável definir o valor como nenhum.

  7. Para a variável OTEL_LOGS_EXPORTER, é recomendável definir o valor como nenhum.

  8. Para a variável OTEL_TRACES_EXPORTER, você precisa definir o valor como otlp (isso é opcional e será o valor padrão se essa variável de ambiente não estiver definida).

  9. Para a variável OTEL_EXPORTER_OTLP_PROTOCOL, você precisa definir o valor como http/protobuf (isso é opcional e será o valor padrão se essa variável de ambiente não estiver definida). O endpoint do OTLP do X-Ray atualmente oferece suporte apenas ao protocolo HTTP.

  10. Agora, a aplicação deve estar sendo executada com a instrumentação Java do AWS Distro para OpenTelemetry e vai gerar spans. Esses spans são armazenados no grupo de logs do aws/spans CloudWatch Logs na sua conta. Você também pode visualizar os rastreamentos e as métricas correlacionados com seus spans no console de rastreamentos e métricas do CloudWatch.

  11. Inicie sua aplicação com as variáveis de ambiente que você definiu. Veja um exemplo de um script inicial.

    (Observação: a configuração a seguir é compatível somente com as versões 1.32.2 e posteriores do agente de instrumentação automática do AWS Distro para OpenTelemetry para Java.)

    JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
Node.js

  1. Faça o download da versão mais recente do agente de instrumentação automática em JavaScript do AWS Distro para OpenTelemetry para o Node.js. Você pode fazer a instalação usando o comando:

    npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation

    Para visualizar informações sobre todas as versões lançadas, consulte AWS Distro for OpenTelemetry JavaScript instrumentation.

  2. Para habilitar o exportador que envia rastreamentos diretamente para o endpoint do OTLP do X-Ray e para otimizar os benefícios, use as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação.

  3. Para a variável OTEL_RESOURCE_ATTRIBUTES, especifique as seguintes informações como pares de chave/valor:

    (Opcional) service.name define o nome do serviço. Isso será exibido como o nome do serviço para a aplicação nos painéis do Application Signals. Quando você não fornecer um valor para essa chave, o padrão de UnknownService será usado.

    (Opcional) deployment.environment define o ambiente em que a aplicação é executada. Essa variável será exibida como o ambiente Hospedado em da aplicação nos painéis do Application Signals. Quando você não especificar essa variável, um dos seguintes padrões será usado:

    • Se for uma instância que faz parte de um grupo do Auto Scaling, ela será definida como ec2:name-of-Auto-Scaling-group.

    • Se for uma instância do Amazon EC2 que não faz parte de um grupo do Auto Scaling, ela será definida como ec2:default.

    • Se for um host on-premises, ele será definido como generic:default.

    Essa variável de ambiente é usada somente pelo Application Signals, e é convertida em anotações de rastreamentos do X-Ray e em dimensões de métricas do CloudWatch.

  4. Para a variável OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, especifique o endpoint de rastreamentos do OTLP do X-Ray: https://xray.[AWSRegion].amazonaws.com/v1/traces.

    Por exemplo:

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. Para a variável OTEL_METRICS_EXPORTER, é recomendável definir o valor como nenhum. As métricas do Application Signals são geradas pelo endpoint do OTLP.

  6. Para a variável OTEL_LOGS_EXPORTER, é recomendável definir o valor como nenhum.

  7. Para a variável OTEL_TRACES_EXPORTER, você precisa definir o valor como otlp (isso é opcional e será o valor padrão se essa variável de ambiente não estiver definida).

  8. Para a variável OTEL_EXPORTER_OTLP_PROTOCOL, você precisa definir o valor como http/protobuf (isso é opcional e será o valor padrão se essa variável de ambiente não estiver definida). O endpoint do OTLP do X-Ray atualmente oferece suporte apenas ao protocolo HTTP.

  9. Agora, a aplicação deve estar sendo executada com a instrumentação Java do AWS Distro para OpenTelemetry e vai gerar spans. Esses spans são armazenados no grupo de logs do aws/spans CloudWatch Logs na sua conta. Você também pode visualizar os rastreamentos e as métricas correlacionados com seus spans no console de rastreamentos e métricas do CloudWatch.

  10. Inicie sua aplicação com as variáveis de ambiente que você definiu. Veja um exemplo de um script inicial.

    (Observação: substitua $SVC_NAME pelo nome da aplicação. Isso é exibido como o nome da aplicação.

    OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node —require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
Python

  1. Faça download da versão mais recente do agente de instrumentação automática do AWS Distro para OpenTelemetry em Python. Você pode fazer a instalação usando o comando:

    pip install aws-opentelemetry-distro

  2. Para habilitar o exportador para enviar rastreamentos diretamente para o endpoint do OTLP do X-Ray e para otimizar os benefícios, use as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação.

  3. Para a variável OTEL_RESOURCE_ATTRIBUTES, especifique as seguintes informações como pares de chave/valor:

    (Opcional) service.name define o nome do serviço. Isso será exibido como o nome do serviço para a aplicação nos painéis do Application Signals. Quando você não fornecer um valor para essa chave, o padrão de UnknownService será usado.

    (Opcional) deployment.environment define o ambiente em que a aplicação é executada. Essa variável será exibida como o ambiente Hospedado em da aplicação nos painéis do Application Signals. Quando você não especificar isso, um dos seguintes padrões será usado:

    • Se for uma instância que faz parte de um grupo do Auto Scaling, ela será definida como ec2:name-of-Auto-Scaling-group.

    • Se for uma instância do Amazon EC2 que não faz parte de um grupo do Auto Scaling, ela será definida como ec2:default.

    • Se for um host on-premises, ele será definido como generic:default.

    Essa variável de ambiente é usada somente pelo Application Signals, e é convertida em anotações de rastreamentos do X-Ray e em dimensões de métricas do CloudWatch.

  4. Para a variável OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, especifique o endpoint de rastreamentos do OTLP do X-Ray: https://xray.[AWSRegion].amazonaws.com/v1/traces.

    Por exemplo:

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. Para a variável OTEL_METRICS_EXPORTER, é recomendável definir o valor como nenhum. As métricas do Application Signals são geradas pelo endpoint do OTLP.

  6. Para a variável OTEL_LOGS_EXPORTER, é recomendável definir o valor como nenhum.

  7. Para a variável OTEL_TRACES_EXPORTER, você precisa definir o valor como otlp (isso é opcional e será o valor padrão se essa variável de ambiente não estiver definida).

  8. Para a variável OTEL_EXPORTER_OTLP_PROTOCOL, você precisa definir o valor como http/protobuf (isso é opcional e será o valor padrão se essa variável de ambiente não estiver definida). O endpoint do OTLP do X-Ray atualmente oferece suporte apenas ao protocolo HTTP.

  9. Agora, a aplicação deve estar sendo executada com a instrumentação Java do AWS Distro para OpenTelemetry e vai gerar spans. Esses spans são armazenados no grupo de logs do aws/spans CloudWatch Logs na sua conta. Você também pode visualizar os rastreamentos e as métricas correlacionados com seus spans no console de rastreamentos e métricas do CloudWatch.

  10. Inicie sua aplicação com as variáveis de ambiente que você definiu. Veja um exemplo de um script inicial.

    (Observação: substitua $SVC_NAME pelo nome da aplicação e substitua $PYTHON_APP pela localização e pelo nome da aplicação.

    OTEL_METRICS_EXPORTER=none \ 
OTEL_LOGS_EXPORTER=none \ 
OTEL_PYTHON_DISTRO=aws_distro \
 OTEL_PYTHON_CONFIGURATOR=aws_configurator \ 
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
.Net

Para habilitar o exportador que envia rastreamentos diretamente para o endpoint de rastreamentos do OTLP do X-Ray e para otimizar os benefícios, defina as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação. Essas variáveis também são necessárias para configurar a instrumentação do .NET.

  1. Substitua dotnet-service-name na variável de ambiente OTEL_RESOURCE_ATTRIBUTES pelo nome do serviço de sua escolha.

  2. Defina OTEL_TRACES_EXPORTER=none.

  3. Defina OTEL_AWS_SIG_V4_ENABLED=true.

    Um exemplo para Linux.

    export INSTALL_DIR=OpenTelemetryDistribution
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}

export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
export OTEL_TRACES_EXPORTER=none
export OTEL_AWS_SIG_V4_ENABLED=true

export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

    Um exemplo para Windows Server.

    $env:INSTALL_DIR = "OpenTelemetryDistribution" 
$env:CORECLR_ENABLE_PROFILING = 1 
$env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}" 
$env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll" 
$env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps" 
$env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store" 
$env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll" 
$env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR 
$env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"

$env:OTEL_TRACES_EXPORTER=none
$env:OTEL_AWS_SIG_V4_ENABLED=true

$env:OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
$env:OTEL_METRICS_EXPORTER=none
$env:OTEL_LOGS_EXPORTER=none
$env:OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

  4. Inicie a aplicação com as variáveis de ambiente.

  5. (Opcional) Como alternativa, você pode usar os scripts de instalação fornecidos para ajudar na instalação e configuração do pacote de instrumentação automática do AWS Distro for OpenTelemetry .NET.

    Para Linux, baixe e instale o script de instalação do Bash na página de versões do GitHub:

    # Download and Install
curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
chmod +x ./aws-otel-dotnet-install.sh
./aws-otel-dotnet-install.sh
# Instrument
. $HOME/.otel-dotnet-auto/instrument.shexport OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name

    Para Windows Server, baixe e instale o script de instalação do PowerShell na página de versões do GitHub:

    # Download and Install
$module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path
Install-OpenTelemetryCore
# Instrument
Import-Module $download_path
Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
Register-OpenTelemetryForIIS

    Você pode encontrar o pacote NuGet do pacote de instrumentação automática do .NET do AWS Distro para OpenTelemetry no repositório oficial do NuGet. Não deixe de verificar o arquivo README para obter instruções.