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.

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.

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.

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.

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 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. A instrumentação automática está disponível para várias bibliotecas PHP comumente usadas. Para obter mais informações, consulte OpenTelemetry registry.

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 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. Para obter uma lista das bibliotecas de instrumentação lançadas, consulte Registry.

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.

Antes de habilitar o Application Signals para suas aplicações em Python, esteja ciente das considerações apresentadas a seguir.

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.

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 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 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:

Para habilitar o Application Signals com o formato do módulo ESM no Node.js, fornecemos diferentes configurações para plataformas distintas:

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 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.

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:

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.

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:

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
}

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

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.