# Sistemas compatíveis
O Application Signals é compatível e foi testado no Amazon EKS, no Kubernetes nativo, no Amazon ECS e no Amazon EC2. As instruções para habilitar o Application Signals no Amazon EC2 devem funcionar em qualquer plataforma que seja compatível com o agente do CloudWatch e o AWS Distro para OpenTelemetry.
**Topics**
+ [Compatibilidade com Java](#CloudWatch-Application-Signals-supportmatrix-java)
+ [Compatibilidade do .NET](#CloudWatch-Application-Signals-supportmatrix-dotnet)
+ [Compatibilidade com PHP](#php-compatibility)
+ [Compatibilidade com Ruby](#ruby-compatibility)
+ [Compatibilidade com Python](#CloudWatch-Application-Signals-supportmatrix-python)
+ [Compatibilidade com Node.js](#CloudWatch-Application-Signals-supportmatrix-node)
+ [Compatibilidade com Golang](#golang-compatibility)
+ [Matriz de compatibilidade das versões do runtime](#rumtime-version-matix)
+ [Problemas conhecidos](#AppSignals-Issues)
## Compatibilidade com Java
O Application Signals é compatível com as aplicações em Java e as mesmas bibliotecas e estruturas em Java que o AWS Distro para OpenTelemetry. Para obter mais informações, consulte [Supported libraries, frameworks, application servers, and JVMs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).
## Compatibilidade do .NET
O Application Signals é compatível com as mesmas bibliotecas e frameworks do .NET que o AWS Distro para OpenTelemetry. Para obter mais informações, consulte [Supported instrumentations](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/internal/instrumentation-libraries.md).
O Application Signals é compatível com aplicações .NET que estão sendo executadas em CPUs x86-64 ou ARM64, além de ser compatível com os sistemas operacionais Linux x64, Linux ARM64 e Microsoft Windows Server 2022 x64.
**nota**
O SDK do AWS Distro for Open Telemetry (ADOT) para .NET não é compatível com o SDK da AWS para o .NET V4. Use o SDK da AWS do .NET V3 para total compatibilidade com o Application Signals.
## Compatibilidade com PHP
O Application Signals é compatível com aplicações PHP com instrumentação de código Zero do OpenTelemetry. Não há nenhum SDK do AWS Distro para OpenTelemetry (ADOT) disponível para essa finalidade. Você deve usar o SDK padrão da instrumentação do OpenTelemetry com a [Pesquisa de Transações](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) habilitada. Para começar a usar a instrumentação de código zero em PHP, siga estas etapas dos documentos de instrumentação do OpenTelemetry PHP, [PHP zero-code instrumentation](https://opentelemetry.io/docs/zero-code/php/). A instrumentação automática está disponível para várias bibliotecas PHP comumente usadas. Para obter mais informações, consulte [OpenTelemetry registry](https://packagist.org/search/?query=open-telemetry%3Dinstrumentation).
## Compatibilidade com Ruby
O Application Signals é compatível com aplicações Ruby com instrumentação de código Zero do OpenTelemetry. Não há nenhum SDK do AWS Distro para OpenTelemetry (ADOT) disponível para essa finalidade. Você deve usar o SDK padrão da instrumentação do OpenTelemetry com a [Pesquisa de Transações](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) habilitada. Para começar a usar a instrumentação de código zero em PHP, siga estas etapas dos documentos de instrumentação do OpenTelemetry PHP, [Ruby zero-code instrumentation](https://opentelemetry.io/docs/languages/ruby/getting-started/#instrumentation). Para obter uma lista das bibliotecas de instrumentação lançadas, consulte [Registry](https://opentelemetry.io/ecosystem/registry/?language=rubycomponent=instrumentation).
## Compatibilidade com Python
O Application Signals oferece suporte às mesmas bibliotecas e estruturas que o AWS Distro para OpenTelemetry. Para obter mais informações, consulte **Supported packages** em [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/README.md).
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](https://github.com/open-telemetry/opentelemetry-operator/issues/2302).
+ Para aplicações em Django, existem configurações adicionais necessárias, descritas na [documentação do OpenTelemetry em Python](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html).
+ 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.
## Compatibilidade com Node.js
O Application Signals é compatível com as mesmas bibliotecas e estruturas para Node.js que o AWS Distro para OpenTelemetry. Para obter mais informações, consulte [Supported instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main).
### Limitações conhecidas sobre o uso de ESM com o Node.js
O AWS Distro para OpenTelemetry no Node.js é compatível com dois sistemas de módulos: o ECMAScript Modules (ESM) e o CommonJS (CJS). Para habilitar o Application Signals, recomendamos o uso do formato de módulo CJS, pois o fornecimento de suporte para o módulo ESM em JavaScript no OpenTelemetry ainda é experimental e está em desenvolvimento. Para obter mais detalhes, consulte [ECMAScript Modules vs. CommonJS](https://github.com/open-telemetry/opentelemetry-js/blob/eb3ca4fb07ee31c62093f5fcec56575573c902ce/doc/esm-support.md) no GitHub.
Para determinar se a aplicação está usando CJS, em vez de ESM, verifique se ela não atende às condições necessárias para habilitar o ESM. Para obter mais informações sobre essas condições, consulte [Enabling](https://nodejs.org/api/esm.html#enabling) na documentação do Node.js.
O AWS Distro para OpenTelemetry no Node.js disponibiliza suporte limitado ao formato de módulo ESM, com base no suporte experimental ao ESM fornecido em JavaScript pelo OpenTelemetry. Essas limitações significam que:
+ A versão do Node.js deve ser 18.19.0 ou versões posteriores.
+ A aplicação do Node.js que você deseja instrumentar deve incluir `@aws/aws-distro-opentelemetry-node-autoinstrumentation` e `@opentelemetry/instrumentation` como dependências.
+ A aplicação do Node.js que você deseja instrumentar deve ser iniciada com a seguinte opção de nó:
```
NODE_OPTIONS=' --import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs'
```
Para habilitar o Application Signals com o formato do módulo ESM no Node.js, fornecemos diferentes configurações para plataformas distintas:
+ **Amazon EKS** – [Configuração de uma aplicação do Node.js usando o formato de módulo ESM](CloudWatch-Application-Signals-Enable-EKS.md#EKS-NodeJs-ESM)
+ **Amazon ECS com estratégia de sidecar** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-ECS-Sidecar.md#ECS-NodeJs-ESM)
+ **Amazon ECS com estratégia de daemon** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-ECS-Daemon.md#ECSDaemon-NodeJs-ESM)
+ **Amazon ECS com o AWS CDK**
+ **Amazon EC2** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-Enable-EC2Main.md#EC2-NodeJs-ESM)
+ **Kubernetes** – [Configuração de uma aplicação do Node.js usando o formato de módulo ESM](CloudWatch-Application-Signals-Enable-KubernetesMain.md#Kubernetes-NodeJs-ESM)
## Compatibilidade com Golang
O Application Signals é compatível com aplicações Golang com instrumentação de código Zero do OpenTelemetry. Não há nenhum SDK do AWS Distro para OpenTelemetry (ADOT) disponível para essa finalidade. Você deve usar o SDK padrão da instrumentação do OpenTelemetry com a [Pesquisa de Transações](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) habilitada. [Para começar a usar a instrumentação de código zero no Golang, siga estas etapas dos documentos de instrumentação do OpenTelemetry Golang, Getting Started with OpenTelemetry Go Automatic Instrumentation.](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/getting-started.md)
### Considerações de implementação da instrumentação do Golang
Confira mais detalhes importantes de implementação para usar a instrumentação do Golang. Esta orientação explica como implementar a propagação explícita de contexto em aplicações Golang e configurar o Application Signals. A implementação adequada da instrumentação do Golang ajuda você a rastrear e analisar a performance da sua aplicação de forma eficaz.
#### Instrumentação do AWS SDK
A biblioteca de instrumentação automática do Golang não é compatível com a instrumentação do AWS SDK pronta para uso. Você deve usar a instrumentação da biblioteca `otelaws` junto com o agente de instrumentação automática:
1. Instale a dependência necessária:
```
go get go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws
```
1. Adicione a seguinte linha à sua aplicação:
```
otelaws.AppendMiddlewares(&cfg.APIOptions)
```
1. Crie clientes subsequentes da AWS com o objeto `aws.Config` anterior:
```
s3Client := s3.NewFromConfig(cfg)
```
O exemplo a seguir vai gerar intervalos para chamadas da AWS e se integrar à instrumentação automática.
```
func handleRequest(ctx context.Context) error {
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
return err
}
// Add OpenTelemetry instrumentation middleware to the AWS config
otelaws.AppendMiddlewares(&cfg.APIOptions)
// Create S3 client with the instrumented config
s3Client := s3.NewFromConfig(cfg)
// Now any operations with this client will be traced
// with the context from the upstream call
_, err = s3Client.ListBuckets(ctx, &s3.ListBucketsInput{})
return err
}
```
Para obter informações sobre como configurar o executável de instrumentação automática, consulte [Configuration methods](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/configuration.md).
#### Instrumentação de chamadas HTTP
As chamadas HTTP podem dividir rastreamentos quando o contexto não é passado entre as solicitações. Os clientes HTTP devem usar `NewRequestWithContext()` em vez de `NewRequest()` para garantir que o serviço downstream use o mesmo contexto. Quando os dois serviços têm agentes de instrumentação, as extensões se conectam com o mesmo ID de rastreamento para fornecer visibilidade de ponta a ponta.
```
func makeDownstreamCall(ctx context.Context, url string) ([]byte, error) {
client := &http.Client{}
// Create request with context from the upstream call
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return nil, err
}
// Execute the request
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
}
```
#### Instrumentação de chamadas SQL
As extensões SQL poderão ser desconectadas de sua extensão principal, fazendo com que as chamadas do cliente sejam inferidas como extensões do servidor. Isso ocorre quando as chamadas SQL não recebem o contexto de seus manipuladores upstream. As chamadas SQL padrão como `Query` e `Exec` usam `context.Background()` por padrão, não o contexto do chamador upstream. Substitua as chamadas SQL padrão por seus equivalentes com reconhecimento de contexto:
+ Use `QueryContext` em vez de `Query`
+ Use `ExecContext` em vez de `Exec`
Esses métodos passam o contexto da solicitação upstream para as chamadas de banco de dados, mantendo a continuidade adequada do rastreamento.
```
func queryDatabase(ctx context.Context, db *sql.DB, userID string) (*sql.Rows, error) {
// This breaks the trace context
// row := db.Query("SELECT name FROM users WHERE id = $1", userID)
// This passes the context from the upstream call for trace continuity
rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE id = $1", userID)
return rows, error
}
```
**nota**
Atualmente, o atributo `db.system` não é compatível com chamadas SQL. Essa limitação afeta a capacidade do CloudWatch de identificar com precisão os clientes do banco de dados. Como resultado, as dependências exibirão **UnknownRemoteService** em vez do nome do cliente de banco de dados que está fazendo a consulta.
#### Detectores de recursos
Atualmente, a instrumentação automática do Go não é compatível com a configuração de detectores de recursos no runtime. A comunidade do OpenTelemetry está trabalhando em um recurso para configurar detectores de recursos usando variáveis de ambiente. Procure esse recurso em uma atualização futura. Enquanto isso, você pode usar o agente do CloudWatch com instrumentação automática para gerar automaticamente atributos de recursos do host.
## Matriz de compatibilidade das versões do runtime
| Linguagem | Versão Runtime |
| --- | --- |
| Java | JVM, versões 8, 11, 17, 21 e 23 |
| Python | Python, as versões 3.9 e posteriores são compatíveis |
| .NET | As versões 1.6.0 e inferiores são compatíveis com o .NET 6 e 8, além do .NET Framework 4.6.2 e versões posteriores As versões 1.7.0 e superiores são compatíveis com o .NET 8 e 9, além do .NET Framework 4.6.2 e versões posteriores |
| Node.js | Node.js, versões 14, 16, 18, 20 e 22 |
| PHP | PHP, versões 8.0 e posteriores |
| Ruby | CRuby >= 3,1, JRuby >= 9,3.2.0 ou TruffleRuby >= 22,1 |
| Golang | Golang, versões 1.18 e posteriores |
## Problemas conhecidos
Sabemos que a coleção de métricas de runtime na versão v1.32.5 do Java SDK não funciona com aplicações que usam o JBoss Wildfly. Esse problema se estende ao complemento Amazon CloudWatch Observability EKS, afetando as versões `2.3.0-eksbuild.1` até `2.6.0-eksbuild.1`. O problema foi corrigido na versão `v1.32.6` do Java SDK e na versão `v3.0.0-eksbuild.1` do complemento Amazon CloudWatch Observability para EKS.
Se você for afetado, atualize a versão do Java SDK ou desabilite a coleção de métricas de runtime adicionando a variável de ambiente `OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false` à sua aplicação.