Configurar o registro em log no SDK do Azure para Java

Artigo
05/01/2024

Este artigo apresenta uma visão geral de como habilitar o registro log em aplicativos que usam o SDK do Azure para Java. As bibliotecas de clientes do Azure para Java têm duas opções de registro em log:

Uma estrutura de registro em log interna para fins de depuração temporária.
Suporte para registro em log usando a interface do SLF4J.

Recomendamos que você use SLF4J porque ele é bem conhecido no ecossistema Java e está bem documentado. Para obter mais informações, confira o Manual do usuário do SLF4J.

Este artigo contém links para outros artigos que abrangem muitas das populares estruturas de registro em log do Java. Esses outros artigos apresentam exemplos de configuração e descrevem como as bibliotecas de clientes do Azure podem usar as estruturas de registro em log.

Qualquer que seja a configuração de log que você usar, a mesma saída de log estará disponível em ambos os casos, pois toda a saída de log nas bibliotecas de cliente do Azure para Java é roteada por uma abstração de ClientLogger do azure-core.

O restante deste artigo detalha a configuração de todas as opções de registro em log disponíveis.

Habilitar registro em log de solicitação/resposta HTTP

O log de solicitações e respostas HTTP está desativado por padrão. Você pode configurar clientes que se comunicam com os serviços do Azure por HTTP para gravar um registro de log para cada solicitação e resposta (ou exceção) recebidas.

Se você usar o OpenTelemetry, considere usar o rastreamento distribuído em vez de registrar solicitações HTTP. Para obter mais informações, consulte Configurar o rastreamento no SDK do Azure para Java.

Configurar o log HTTP com uma variável de ambiente

Você pode usar a variável de AZURE_HTTP_LOG_DETAIL_LEVEL ambiente para habilitar logs HTTP globalmente. Essa variável oferece suporte aos seguintes valores:

NONE: Os logs HTTP estão desabilitados. Esse valor é o padrão.
BASIC: Os logs HTTP contêm método de solicitação, URL de solicitação limpa, contagem de tentativas, código de resposta e o comprimento do conteúdo para corpos de solicitação e resposta.
HEADERS: Os logs HTTP incluem todos os detalhes básicos e também incluem cabeçalhos que são conhecidos por serem seguros para fins de registro - ou seja, eles não contêm segredos ou informações confidenciais. A lista completa de nomes de cabeçalho está disponível na classe HttpLogOptions .
BODY_AND_HEADERS: Os logs HTTP incluem todos os detalhes fornecidos pelo HEADERS nível e também incluem corpos de solicitação e resposta, desde que sejam menores que 16 KB e imprimíveis.

Observação

A URL da solicitação é higienizada - ou seja, todos os valores de parâmetro de consulta são editados, exceto o api-version valor. Bibliotecas de cliente individuais podem adicionar outros parâmetros de consulta que são conhecidos por serem seguros para a lista de permissões.

Por exemplo, a URL de assinatura de acesso compartilhado (SAS) do Armazenamento de Blobs do Azure é registrada no seguinte formato: https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Aviso

O registro em log de corpos de solicitação e resposta não é recomendado na produção porque eles podem conter informações confidenciais, afetar significativamente o desempenho, alterar a forma como o conteúdo é armazenado em buffer e ter outros efeitos colaterais.

Configurar o log HTTP no código

Os construtores de clientes do Azure que implementam a interface HttpTrait<T> dão suporte à configuração de log HTTP baseada em código. A configuração baseada em código se aplica a instâncias de cliente individuais e fornece mais opções e personalizações em comparação com a configuração de variável de ambiente.

Para configurar logs, passe uma instância de HttpLogOptions para o httpLogOptions método no construtor de cliente correspondente. O código a seguir mostra um exemplo para o serviço de Configuração de Aplicativo:

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Esse código habilita logs HTTP com cabeçalhos e adiciona o cabeçalho de Accept-Ranges resposta e o label parâmetro de consulta às listas de permissões correspondentes. Após essa alteração, esses valores devem aparecer nos logs produzidos.

Para obter a lista completa de opções de configuração, consulte a documentação HttpLogOptions.

Agente padrão (para depuração temporária)

Como observado, todas as bibliotecas de clientes do Azure usam SLF4J para registro em log, mas há um agente padrão de captura de logs interno nas bibliotecas de clientes do Azure para Java. Esse registrador padrão é fornecido para casos em que um aplicativo é implantado e o log é necessário, mas não é possível reimplantar o aplicativo com um registrador SLF4J incluído. Para habilitar esse registrador, você deve primeiro ter certeza de que nenhum registrador SLF4J existe (porque ele tem precedência) e, em seguida, definir a AZURE_LOG_LEVEL variável de ambiente. A seguinte tabela mostra os valores permitidos para essa variável de ambiente:

Nível de log	Valores de variáveis de ambiente permitidos
VERBOSE	`verbose`, `debug`
INFORMATIONAL	`info`, `information`, `informational`
WARNING	`warn`, `warning`
ERROR	`err`, `error`

Depois que a variável de ambiente for definida, reinicie o aplicativo para habilitá-la e fazer com que entre em vigor. Esse registrador registra no console e não fornece os recursos avançados de personalização de uma implementação SLF4J, como sobreposição e registro em arquivo. Para desativar o registro em log novamente, basta remover a variável de ambiente e reiniciar o aplicativo.

Registro em log do SLF4J

Por padrão, você deve configurar o registro em log usando uma estrutura de log com suporte do SLF4J. Primeiro, inclua uma implementação de registro em log do SLF4J relevante como uma dependência do seu projeto. Para obter mais informações, confira Como declarar as dependências do projeto para registro em log no manual do usuário do SLF4J. Em seguida, configure o registrador para funcionar conforme necessário em seu ambiente, como definir níveis de log, configurar quais classes fazem e não registram e assim por diante. Alguns exemplos são fornecidos por meio dos links deste artigo, mas para obter mais informações, consulte a documentação da estrutura de log escolhida.

Formato de log

As estruturas de log oferecem suporte a formatação e layouts de mensagens de log personalizados. Recomendamos incluir pelo menos os seguintes campos para tornar possível solucionar problemas de bibliotecas de cliente do Azure:

Data e hora com precisão de milissegundos
Gravidade do log
Nome do registrador
Nome do thread
Mensagem

Para obter exemplos, consulte a documentação da estrutura de log que você usa.

Registro em log estruturado

Além de registrar as propriedades comuns mencionadas anteriormente, as bibliotecas de cliente do Azure anotam mensagens de log com contexto extra, quando aplicável. Por exemplo, você pode ver logs formatados em JSON contendo az.sdk.message com contexto escrito como outras propriedades raiz, conforme mostrado no exemplo a seguir:

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

Ao enviar logs para o Azure Monitor, você pode usar a linguagem de consulta do Kusto para analisá-los. A consulta a seguir fornece um exemplo:

traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Observação

Os logs da biblioteca de cliente do Azure são destinados à depuração ad-hoc. Não recomendamos confiar no formato de log para alertar ou monitorar seu aplicativo. As bibliotecas de cliente do Azure não garantem a estabilidade de mensagens de log ou chaves de contexto. Para tais fins, recomendamos o uso de rastreamento distribuído. O agente Java do Application Insights fornece garantias de estabilidade para telemetria de solicitação e dependência. Para obter mais informações, consulte Configurar o rastreamento no SDK do Azure para Java.

Próximas etapas

Agora que você sabe como o log funciona no SDK do Azure para Java, considere revisar os seguintes artigos. Estes artigos fornecem orientação sobre como configurar algumas das estruturas de log Java mais populares para trabalhar com SLF4J e as bibliotecas de cliente Java:

Compartilhar via