Configurar o log no SDK do Azure para Java

2025-04-16

Este artigo fornece uma visão geral de como habilitar o registro em 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 o SLF4J porque ele é bem conhecido no ecossistema java e está bem documentado. Para mais informações, consulte o manual do usuário SLF4J .

Este artigo vincula-se a outros artigos que abrangem muitas das estruturas populares de log do Java. Esses outros artigos fornecem exemplos de configuração e descrevem como as bibliotecas de clientes do Azure podem usar as estruturas de log.

Seja qual for a configuração de log usada, a mesma saída de log está disponível em ambos os casos, pois todas as saídas de log nas bibliotecas de clientes do Azure para Java são roteadas por meio de uma abstração do azure-core ClientLogger .

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

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

A solicitação HTTP e o log de resposta estão desativados 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) que eles recebem.

Se você utiliza OpenTelemetry, considere usar rastreamento distribuído, em vez de logar, para 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 ambiente AZURE_HTTP_LOG_DETAIL_LEVEL para ativar logs HTTP globalmente. Essa variável dá suporte aos seguintes valores:

NONE: os logs HTTP estão desabilitados. Esse valor é o padrão.
BASIC: Os registros HTTP contêm o método da solicitação, a URL da solicitação sanitizada, o número de tentativas, o código de resposta e o comprimento do conteúdo para os corpos das solicitações e respostas.
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 em log- 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 é sanitizada, ou seja, todos os valores de parâmetro de consulta são redigidos, exceto pelo api-version valor. Bibliotecas de cliente individuais podem adicionar outros parâmetros de consulta que são conhecidos por serem seguros à lista de permissões.

Por exemplo, a URL de SAS (assinatura de acesso compartilhado) 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

Registrar em log os corpos de solicitação e resposta não é recomendado na produção porque 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 registro em 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 método httpLogOptions no construtor de clientes correspondente. O código a seguir mostra um exemplo para o serviço de Configuração de Aplicativos:

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 resposta Accept-Ranges e o parâmetro de consulta label à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 do 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 agente padrão é fornecido para casos em que um aplicativo é implantado e o registro em log é necessário, mas não é possível reimplantar o aplicativo com um agente SLF4J incluído. Para habilitar este logger, primeiro você deve ter certeza de que nenhum logger SLF4J existe (porque ele tem precedência) e, em seguida, definir a variável de ambiente AZURE_LOG_LEVEL. A tabela a seguir mostra os valores permitidos para essa variável de ambiente:

Nível de log	Valores de variável de ambiente permitidos
PROLIXO	`verbose`, `debug`
INFORMATIVO	`info` `information` `informational`
AVISO	`warn`, `warning`
ERRO	`err`, `error`

Depois que a variável de ambiente for definida, reinicie o aplicativo para permitir que a variável de ambiente entre em vigor. Esse agente registra em log no console e não oferecerá os recursos de personalização avançada de uma implementação do SLF4J, como substituição e registro em log no arquivo. Para desativar o 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 logging usando um framework de logging suportado por SLF4J. Primeiro, inclua uma implementação de log 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 agente para funcionar conforme necessário em seu ambiente, como definir os níveis de registro em log, configurar quais classes registrar e não registrar em log e assim por diante. Alguns exemplos são fornecidos por meio dos links neste artigo, mas para obter mais informações, consulte a documentação da estrutura de log escolhida.

Formato de log

As estruturas de log dão suporte à formatação e layouts personalizados de mensagens de log. É recomendável incluir pelo menos os seguintes campos para tornar possível solucionar problemas de bibliotecas de clientes 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 registros que você usa.

Registro em log estruturado

Além de registrar as propriedades comuns mencionadas anteriormente, as bibliotecas de clientes 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 o contexto sendo 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 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 clientes do Azure destinam-se à depuração ad hoc. Não recomendamos depender do formato de log para alertar ou monitorar seu aplicativo. As bibliotecas de clientes do Azure não garantem a estabilidade das mensagens de log ou das chaves de contexto. Para esses fins, é recomendável usar o 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 registro em log funciona no SDK do Azure para Java, considere revisar os artigos a seguir. Estes artigos fornecem diretrizes sobre como configurar algumas das estruturas de log java mais populares para trabalhar com o SLF4J e as bibliotecas de cliente Java:

Compartilhar via