Configurar o log no SDK do Azure para Java

Artigo
05/01/2024

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 cliente do Azure para Java têm duas opções de log:

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

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

Este artigo contém links para outros artigos que abrangem muitos dos frameworks de log Java populares. Estes outros artigos fornecem exemplos de configuração e descrevem como as bibliotecas de cliente 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 porque toda a saída de log nas bibliotecas de cliente do Azure para Java é roteada por meio de uma abstração azure-core ClientLogger .

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

Habilitar o log de solicitação/resposta HTTP

O log de solicitação e resposta 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) que receberem.

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

Configurar o log HTTP com uma variável de ambiente

Você pode usar a AZURE_HTTP_LOG_DETAIL_LEVEL variável de ambiente para habilitar logs HTTP globalmente. Esta variável suporta os seguintes valores:

NONE: Os logs HTTP estão desativados. Este valor é a predefiniçã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.

Nota

A URL da solicitação é limpa, ou seja, todos os valores de parâmetros 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 Blob 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 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 registro em log HTTP no código

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

Para configurar logs, passe uma instância de HttpLogOptions para o httpLogOptions método no construtor de clientes 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.

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

Como observado, todas as bibliotecas de cliente do Azure usam SLF4J para registro, mas há um registrador padrão de fallback incorporado às bibliotecas de cliente do Azure para Java. Esse registrador 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 registrador SLF4J incluído. Para habilitar esse logger, você deve primeiro ter certeza de que nenhum logger SLF4J existe (porque ele tem precedência) e, em seguida, definir a variável de AZURE_LOG_LEVEL ambiente. A tabela a seguir mostra os valores permitidos para essa variável de ambiente:

Nível do registo	Valores de variáveis de ambiente permitidos
VERBOSO	`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 registrador registra no console e não fornece os recursos avançados de personalização de uma implementação SLF4J, como rollover e registro em arquivo. Para desativar o logoff novamente, basta remover a variável de ambiente e reiniciar o aplicativo.

Registo SLF4J

Por padrão, você deve configurar o registro em log usando uma estrutura de log suportada por SLF4J. Primeiro, inclua uma implementação de log SLF4J relevante como uma dependência do seu projeto. Para obter mais informações, consulte Declarando dependências do projeto para registro em log no manual do usuário SLF4J. Em seguida, configure seu 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 através dos links neste artigo, mas para obter mais informações, consulte a documentação da estrutura de log escolhida.

Formato de registo

As estruturas de registro em log suportam formatação e layouts de mensagens de log personalizadas. Recomendamos incluir pelo menos os seguintes campos para possibilitar a solução de problemas das bibliotecas de cliente do Azure:

Data e hora com precisão de milissegundos
Severidade do log
Nome do registador
Nome do thread
Mensagem

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

Registos estruturados

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

Nota

Os logs da biblioteca de cliente do Azure destinam-se à 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 esses 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 rastreamento no SDK do Azure para Java.

Próximos passos

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

Partilhar via