Habilitar o Application Signals no Amazon EC2
Para as aplicações em execução no Amazon EC2 ou em outros tipos de instância, você mesmo instala e configura o agente do CloudWatch e o AWS Distro para OpenTelemetry. Nessas arquiteturas habilitadas com uma configuração personalizada do Application Signals, o Application Signals não descobre automaticamente os nomes dos seus serviços ou dos hosts ou clusters em que eles são executados. Você deve especificar esses nomes durante a configuração personalizada, e os nomes especificados serão exibidos nos painéis do Application Signals.
As instruções nesta seção são destinadas a aplicações em Java, Python e .NET. As etapas apresentadas foram testadas em instâncias do Amazon EC2, mas também devem funcionar em outras arquiteturas compatíveis com o AWS Distro para OpenTelemetry.
Requisitos
Para obter suporte para o Application Signals, é necessário usar a versão mais recente do agente do CloudWatch e do agente do AWS Distro para OpenTelemetry.
Você deve ter a AWS CLI instalada na instância. Recomendamos a versão 2 da AWS CLI, mas a versão 1 também deve funcionar. Para obter mais informações sobre como instalar a AWS CLI, consulte Instalar ou atualizar para a versão mais recente da AWS CLI.
Etapa 1: habilitar o Application Signals em sua conta
Caso ainda não tenha habilitado o Application Signals nessa conta, você deve conceder as permissões necessárias para o Application Signals descobrir seus serviços. Para fazê-lo, siga as etapas apresentadas a seguir. Você precisa fazer isso somente uma vez para a conta.
Como habilitar o Application Signals para suas aplicações
Abra o console do CloudWatch em https://console.aws.amazon.com/cloudwatch/.
No painel de navegação, escolha Serviços.
Escolha Começar a descobrir os serviços.
Marque a caixa de seleção e escolha Começar a descobrir os serviços.
Ao concluir essa etapa pela primeira vez em sua conta, o Application Signals cria o perfil vinculado ao serviço AWSServiceRoleForCloudWatchApplicationSignals. Essa função concede as seguintes permissões ao Application Signals:
-
xray:GetServiceGraph
-
logs:StartQuery
-
logs:GetQueryResults
-
cloudwatch:GetMetricData
-
cloudwatch:ListMetrics
-
tag:GetResources
Para obter mais informações sobre essa função, consulte Permissões de perfis vinculados ao serviço para o CloudWatch Application Signals.
Etapa 2: fazer download e iniciar o agente do CloudWatch
Para instalar o agente do CloudWatch como parte da habilitação do Application Signals em uma instância do Amazon EC2 ou em um host on-premises
Faça download da versão mais recente do agente do CloudWatch para a instância. Se a instância já tiver o agente do CloudWatch instalado, talvez seja necessário atualizá-lo. Somente as versões do agente liberadas em 30 de novembro de 2023, ou após essa data, oferecem suporte ao CloudWatch Application Signals.
Para obter informações sobre como fazer download do agente do CloudWatch, consulte Baixar o pacote do atendente do CloudWatch.
Antes de iniciar o agente do CloudWatch, configure-o para habilitar o Application Signals. O exemplo apresentado a seguir corresponde a uma configuração do agente do CloudWatch que habilita o Application Signals para as métricas e os rastreamentos em um host do EC2.
Recomendamos que você coloque esse arquivo em /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json nos sistemas Linux.
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
Anexe a política do IAM CloudWatchAgentServerPolicy ao perfil do IAM da sua instância do Amazon EC2. Para obter permissões para hosts on-premises, consulte Permissões para servidores on-premises.
Faça login no AWS Management Console e abra o console do IAM, em https://console.aws.amazon.com/iam/.
Escolha Perfis e localize o perfil usado pela sua instância do Amazon EC2. Em seguida, escolha o nome desse perfil.
Na guia Permissões, escolha Adicionar permissões e, em seguida, Anexar políticas.
Localize CloudWatchAgentServerPolicy. Use a caixa de pesquisa, se necessário. Em seguida, marque a caixa de seleção dessa política e escolha Adicionar permissões.
Inicie o agente do CloudWatch ao inserir os comandos apresentados a seguir. Substitua agent-config-file-path pelo caminho para o arquivo de configuração do agente do CloudWatch, como ./amazon-cloudwatch-agent.json. Você deve incluir o prefixo file:, conforme mostrado.
export CONFIG_FILE_PATH=./amazon-cloudwatch-agent.json
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-a fetch-config \
-m ec2 -s -c file:agent-config-file-path
Permissões para servidores on-premises
Para um host on-premises, você precisará fornecer à AWS uma autorização ao seu dispositivo.
Para configurar permissões para um host on-premises
Crie o usuário do IAM a ser usado para fornecer permissões ao seu host on-premises:
Abra o console do IAM, em https://console.aws.amazon.com/iam/.
Escolha Usuários, Criar usuário.
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. Em seguida, escolha Próximo
Na página Definir permissões, em Opções de permissões, escolha Anexar políticas diretamente.
Na lista de Políticas de permissões, selecione a política CloudWatchAgentServerPolicy para adicionar ao seu usuário. Em seguida, escolha Próximo.
Na página Revisar e criar, verifique se você está satisfeito com o nome de usuário e se a política CloudWatchAgentServerPolicy está no Resumo de permissões.
Escolha Criar usuário
Crie e recupere sua chave de acesso da AWS e uma chave secreta:
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.
Na página do usuário, escolha a guia Credenciais de segurança. Depois, na seção Chaves de acesso, escolha Criar chave de acesso.
Em Criar chave de acesso: etapa 1, escolha Command Line Interface (CLI).
Em Criar chave de acesso: etapa 2, insira uma tag opcional e escolha Próximo.
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.
Selecione Done (Concluído).
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
Etapa 3: instrumentalizar a aplicação e iniciá-la
A próxima etapa corresponde à instrumentação da sua aplicação para o CloudWatch Application Signals.
- Java
-
Para instrumentalizar as aplicações em Java como parte da habilitação do Application Signals em uma instância do Amazon EC2 ou um host on-premises
Faça download da versão mais recente do agente de instrumentação automática em Java do AWS Distro para OpenTelemetry. É possível fazer download da versão mais recente ao usar este link. É possível visualizar informações sobre todas as versões liberadas em aws-otel-java-instrumentation Releases.
Para otimizar os benefícios do Application Signals, use as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação. Essas informações serão exibidas nos painéis do Application Signals.
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. Se você não fornecer um valor para essa chave, o padrão 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. Caso você não especifique, 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.
Para a variável OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, especifique o URL do endpoint de base para o qual os rastreamentos serão exportados. O agente do CloudWatch mostra 4316 como a porta OLTP. No Amazon EC2, como as aplicações se comunicam com o agente do CloudWatch local, é necessário definir esse valor como OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces.
Para a variável OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT, especifique o URL do endpoint de base para o qual as métricas serão exportadas. O agente do CloudWatch mostra 4316 como a porta OLTP. No Amazon EC2, como as aplicações se comunicam com o agente do CloudWatch local, é necessário definir esse valor como OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics.
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
Para a variável OTEL_METRICS_EXPORTER, recomendamos definir o valor como none. Isso desabilita outros exportadores de métricas para que somente o exportador do Application Signals seja usado.
Defina OTEL_AWS_APPLICATION_SIGNALS_ENABLED como true. Isso gera métricas do Application Signals usando os rastreamentos.
Inicie a aplicação com as variáveis de ambiente listadas na etapa anterior. Veja a seguir um exemplo de um script inicial.
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_EXPORT=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
(Opcional) Para habilitar a correlação de logs, em OTEL_RESOURCE_ATTRIBUTES, defina uma variável de ambiente aws.log.group.names adicional para os grupos de logs da sua aplicação. Ao fazer isso, será possível correlacionar os rastreamentos e métricas da sua aplicação com as entradas de log relevantes desses grupos de logs. Para essa variável, substitua $YOUR_APPLICATION_LOG_GROUP pelos nomes do grupo de logs da sua aplicação. Se você tiver vários grupos de logs, é possível usar um e comercial (&) para separá-los, como neste exemplo: aws.log.group.names=log-group-1&log-group-2. Para permitir que a métrica registre a correlação em log, basta definir essa variável ambiental atual. Para ter mais informações, consulte Habilitar a correlação entre métrica e logs. Para habilitar a correlação entre logs e rastreamento, você também precisará alterar a configuração de registro em log em sua aplicação. Para ter mais informações, consulte Habilitar a correlação entre rastreamento e logs.
Veja a seguir um exemplo de um script inicial que ajuda a habilitar a correlação de logs.
JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORT=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
- Python
-
Como instrumentalizar as aplicações em Python como parte da habilitação do Application Signals em uma instância do Amazon EC2
Faça download da versão mais recente do agente de instrumentação automática do AWS Distro para OpenTelemetry em Python. Instale-o executando o seguinte comando da .
pip install aws-opentelemetry-distro
É possível visualizar informações sobre todas as versões lançadas em AWS Distro for OpenTelemetry Python instrumentation.
Para otimizar os benefícios do Application Signals, use as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação. Essas informações serão exibidas nos painéis do Application Signals.
Para a variável OTEL_RESOURCE_ATTRIBUTES, especifique as seguintes informações como pares de chave/valor:
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. Se você não fornecer um valor para essa chave, o padrão UnknownService será usado.
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. Caso você não especifique, 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 chave de atributo é usada somente pelo Application Signals e é convertida em anotações de rastreamentos do X-Ray e em dimensões de métricas do CloudWatch.
Para a variável OTEL_EXPORTER_OTLP_PROTOCOL, especifique http/protobuf para exportar dados de telemetria por HTTP para os endpoints do agente do CloudWatch listados nas etapas a seguir.
Para a variável OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, especifique o URL do endpoint de base para o qual os rastreamentos serão exportados. O agente do CloudWatch mostra 4316 como a porta OLTP via HTTP. No Amazon EC2, como as aplicações se comunicam com o agente do CloudWatch local, é necessário definir esse valor como OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces.
Para a variável OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT, especifique o URL do endpoint de base para o qual as métricas serão exportadas. O agente do CloudWatch mostra 4316 como a porta OLTP via HTTP. No Amazon EC2, como as aplicações se comunicam com o agente do CloudWatch local, é necessário definir esse valor como OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics.
Para a variável OTEL_METRICS_EXPORTER, recomendamos definir o valor como none. Isso desabilita outros exportadores de métricas para que somente o exportador do Application Signals seja usado.
Defina a variável OTEL_AWS_APPLICATION_SIGNALS_ENABLED como true para que seu contêiner comece a enviar rastreamentos de X-Ray e métricas do CloudWatch para o Application Signals.
Inicie a aplicação com as variáveis de ambiente discutidas na etapa anterior. Veja a seguir um exemplo de um script inicial.
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
Antes de habilitar o Application Signals para suas aplicações em Python, esteja ciente das considerações apresentadas a seguir.
Em algumas aplicações em contêineres, uma variável de ambiente PYTHONPATH ausente pode, às vezes, causar falhas na inicialização da aplicação. Para resolver isso, certifique-se de definir a variável de ambiente PYTHONPATH para o local do diretório de trabalho da sua aplicação. Isso ocorre devido a um problema conhecido com a instrumentação automática do OpenTelemetry. Para obter mais informações sobre esse problema, consulte Python autoinstrumentation setting of PYTHONPATH is not compliant.
Para aplicações em Django, existem configurações adicionais necessárias, descritas na documentação do OpenTelemetry em Python.
Use o sinalizador --noreload para evitar o recarregamento automático.
Defina a variável de ambiente DJANGO_SETTINGS_MODULE para o local do arquivo settings.py da sua aplicação em Django. Isso garante que o OpenTelemetry possa acessar e se integrar adequadamente às suas configurações do Django.
-
(Opcional) Para habilitar a correlação de logs, em OTEL_RESOURCE_ATTRIBUTES, defina uma variável de ambiente aws.log.group.names adicional para os grupos de logs da sua aplicação. Ao fazer isso, será possível correlacionar os rastreamentos e métricas da sua aplicação com as entradas de log relevantes desses grupos de logs. Para essa variável, substitua $YOUR_APPLICATION_LOG_GROUP pelos nomes do grupo de logs da sua aplicação. Se você tiver vários grupos de logs, é possível usar um e comercial (&) para separá-los, como neste exemplo: aws.log.group.names=log-group-1&log-group-2. Para permitir que a métrica registre a correlação em log, basta definir essa variável ambiental atual. Para ter mais informações, consulte Habilitar a correlação entre métrica e logs. Para habilitar a correlação entre logs e rastreamento, você também precisará alterar a configuração de registro em log em sua aplicação. Para ter mais informações, consulte Habilitar a correlação entre rastreamento e logs.
Veja a seguir um exemplo de um script inicial que ajuda a habilitar a correlação de logs.
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
java -jar $MY_PYTHON_APP.jar
- .NET
-
Para instrumentalizar as aplicações em .NET como parte da habilitação do Application Signals em uma instância do Amazon EC2 ou um host on-premises
Faça download da versão mais recente do agente de instrumentação automática para .NET do AWS Distro para OpenTelemetry. Você pode baixar a versão mais recente em aws-otel-dotnet-instrumentation Releases.
Para habilitar o Application Signals, defina as seguintes variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação. Essas variáveis são necessárias para configurar o hook de inicialização da instrumentação .NET, antes de você iniciar sua aplicação .NET.
O seguinte é 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_RESOURCE_ATTRIBUTES=service.name=aws-otel-integ-test
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4316
export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://127.0.0.1:4316/v1/metrics
export OTEL_METRICS_EXPORTER=none
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
export OTEL_TRACES_SAMPLER=xray
export OTEL_TRACES_SAMPLER_ARG=http://127.0.0.1:2000
Veja a seguir 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_RESOURCE_ATTRIBUTES = "service.name=aws-otel-integ-test"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4316"
$env:OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT = "http://127.0.0.1:4316/v1/metrics"
$env:OTEL_METRICS_EXPORTER = "none"
$env:OTEL_AWS_APPLICATION_SIGNALS_ENABLED = "true"
$env:OTEL_TRACES_SAMPLER = "xray"
$env:OTEL_TRACES_SAMPLER_ARG = "http://127.0.0.1:2000"
Inicie a aplicação com as variáveis de ambiente listadas na etapa anterior.
(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.sh
export 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"
Você pode encontrar o pacote NuGet do pacote de instrumentação automática do AWS Distro for OpenTelemetry .NET no repositório oficial do NuGet. Certifique-se de verificar o arquivo README para obter instruções.
- Node.js
-
Como instrumentar as aplicações em Node.js como parte da habilitação do Application Signals em uma instância do Amazon EC2
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. Instale-o executando o seguinte comando da .
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
É possível obter informações sobre todas as versões lançadas em AWS Distro for OpenTelemetry JavaScript instrumentation.
Para otimizar os benefícios do Application Signals, use as variáveis de ambiente para fornecer informações adicionais antes de iniciar a aplicação. Essas informações serão exibidas nos painéis do Application Signals.
Para a variável OTEL_RESOURCE_ATTRIBUTES, especifique as seguintes informações como pares de chave/valor:
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. Se você não fornecer um valor para essa chave, o padrão UnknownService será usado.
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. Caso você não especifique, 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 chave de atributo é usada somente pelo Application Signals e é convertida em anotações de rastreamentos do X-Ray e em dimensões de métricas do CloudWatch.
Para a variável OTEL_EXPORTER_OTLP_PROTOCOL, especifique http/protobuf para exportar dados de telemetria por HTTP para os endpoints do agente do CloudWatch listados nas etapas a seguir.
Para a variável OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, especifique o URL do endpoint de base para o qual os rastreamentos serão exportados. O agente do CloudWatch mostra 4316 como a porta OLTP via HTTP. No Amazon EC2, como as aplicações se comunicam com o agente do CloudWatch local, é necessário definir esse valor como OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces.
Para a variável OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT, especifique o URL do endpoint de base para o qual as métricas serão exportadas. O agente do CloudWatch mostra 4316 como a porta OLTP via HTTP. No Amazon EC2, como as aplicações se comunicam com o agente do CloudWatch local, é necessário definir esse valor como OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics.
Para a variável OTEL_METRICS_EXPORTER, recomendamos definir o valor como none. Isso desabilita outros exportadores de métricas para que somente o exportador do Application Signals seja usado.
Defina a variável OTEL_AWS_APPLICATION_SIGNALS_ENABLED como true para que seu contêiner comece a enviar rastreamentos de X-Ray e métricas do CloudWatch para o Application Signals.
Inicie a aplicação com as variáveis de ambiente discutidas na etapa anterior. Veja a seguir um exemplo de um script inicial.
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
-
(Opcional) Para habilitar a correlação de logs, em OTEL_RESOURCE_ATTRIBUTES, defina uma variável de ambiente aws.log.group.names adicional para os grupos de logs da sua aplicação. Ao fazer isso, será possível correlacionar os rastreamentos e métricas da sua aplicação com as entradas de log relevantes desses grupos de logs. Para essa variável, substitua $YOUR_APPLICATION_LOG_GROUP pelos nomes do grupo de logs da sua aplicação. Se você tiver vários grupos de logs, é possível usar um e comercial (&) para separá-los, como neste exemplo: aws.log.group.names=log-group-1&log-group-2. Para permitir que a métrica registre a correlação em log, basta definir essa variável ambiental atual. Para ter mais informações, consulte Habilitar a correlação entre métrica e logs. Para habilitar a correlação entre logs e rastreamento, você também precisará alterar a configuração de registro em log em sua aplicação. Para ter mais informações, consulte Habilitar a correlação entre rastreamento e logs.
Veja a seguir um exemplo de um script inicial que ajuda a habilitar a correlação de logs.
export OTEL_METRICS_EXPORTER=none \
export OTEL_LOGS_EXPORTER=none \
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
export OTEL_TRACES_SAMPLER=xray \
export OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:2000 \
export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
export OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
Configuração de uma aplicação do Node.js usando o formato de módulo ESM
Fornecemos suporte limitado para aplicações do Node.js com o formato de módulo ESM. Para obter detalhes, consulte Limitações conhecidas sobre o uso de ESM com o Node.js.
Para habilitar o Application Signals em uma aplicação do Node.js com o ESM, será necessário modificar as etapas no procedimento anterior.
Primeiro, instale @opentelemetry/instrumentation à aplicação do Node.js:
npm install @opentelemetry/instrumentation@0.54.0
Em seguida, nas etapas 3 e 4 do procedimento anterior, altere as opções do nó de:
--require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register'
Para o seguinte:
--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs
