SDK do AWS X-Ray para Go

O X-Ray SDK para Go é um conjunto de bibliotecas para aplicações Go que fornece classes e métodos para gerar e enviar dados de rastreamento ao daemon do X-Ray SDK. Os dados de rastreamento incluem informações sobre as solicitações HTTP de entrada atendidas pela aplicação e as chamadas que a aplicação faz para serviços subsequentes usando o SDK da AWS, clientes HTTP ou um conector de banco de dados SQL. Você também pode criar segmentos manualmente e adicionar informações de depuração em anotações e metadados.

Faça download do SDK de seu Repositório do GitHub com go get:

$ go get -u github.com/aws/aws-xray-sdk-go/... 

Para aplicativos web, comece usando a xray.Handlerfunção para rastrear solicitações de entrada. O manipulador de mensagens cria um segmento para cada solicitação rastreada e conclui o segmento quando a resposta é enviada. Embora o segmento esteja aberto, você pode usar os métodos do cliente do SDK para adicionar informações ao segmento e criar subsegmentos para rastrear as chamadas subsequentes. O SDK também registra automaticamente exceções que a aplicação lança enquanto o segmento está aberto.

Para funções do Lambda chamadas por uma aplicação ou um serviço instrumentado, o Lambda lê o cabeçalho de rastreamento e rastreia automaticamente as solicitações amostradas. Para outras funções, você pode configurar o Lambda para amostrar e rastrear solicitações recebidas. Em ambos os casos, o Lambda cria o segmento e o fornece ao X-Ray SDK.

nota

No Lambda, o X-Ray SDK é opcional. Se você não o usar em sua função, mesmo assim o mapa de serviço incluirá um nó para o serviço Lambda e um para cada função do Lambda. Ao adicionar o SDK, você pode instrumentar o código da função para adicionar subsegmentos ao segmento de função registrado pelo Lambda. Consulte AWS Lambda e AWS X-Ray para obter mais informações.

Em seguida, encapsule seu cliente com uma chamada para a função AWS. Essa etapa garante que os instrumentos do X-Ray chamem qualquer método de cliente. Você também pode instrumentar chamadas para bancos de dados SQL.

Depois que você começar a usar o SDK, personalize o comportamento dele configurando o gravador e o middleware. Você pode adicionar plug-ins para registrar dados sobre os recursos de computação que executam sua aplicação, personalizar o comportamento de amostragem, estipulando regras de amostragem, e definir o nível de log para ver mais ou menos informações do SDK nos logs da aplicação.

Registre informações adicionais sobre as solicitações e o trabalho que o a aplicação faz em anotações e metadados. Anotações são simples pares de chave-valor que são indexados para serem usados com expressões de filtro para que você possa pesquisar rastreamentos que contêm dados específicos. As entradas de metadados são menos restritivas e podem registrar matrizes e objetos inteiros: tudo o que pode ser serializado em JSON.

Anotações e metadados

Anotações e metadados são textos arbitrários que você adiciona aos segmentos com o X-Ray SDK. As anotações são indexadas para serem usadas com expressões de filtro. Os metadados não são indexados, mas podem ser visualizados no segmento bruto com o console ou a API do X-Ray. Qualquer pessoa à qual você conceder acesso de leitura ao X-Ray poderá visualizar esses dados.

Quando há uma grande quantidade de clientes instrumentados no código, um único segmento de solicitação pode conter um grande número de subsegmentos, um para cada chamada feita com um cliente instrumentado. Você pode organizar e agrupar subsegmentos integrando chamadas de clientes em subsegmentos personalizados. Você pode criar um subsegmento personalizado para uma função inteira ou qualquer seção de código e registrar metadados e anotações no subsegmento em vez de gravar tudo no segmento principal.

Requisitos

O X-Ray SDK para Go requer o Go 1.9 ou posterior.

O SDK depende das seguintes bibliotecas para compilação e tempo de execução:

• AWS SDK para Go versão 1.10.0 ou mais recente

Essas dependências são declaradas no arquivo README.md do SDK.

Documentação de referência

Depois de fazer download do SDK, crie e hospede a documentação localmente para visualizá-la em um navegador da web.

Para visualizar a documentação de referência

1. Navegando para o diretório $GOPATH/src/github.com/aws/aws-xray-sdk-go (Linux ou Mac) ou para a pasta %GOPATH%\src\github.com\aws\aws-xray-sdk-go (Windows)

2. Execute o comando godoc.

   $ godoc -http=:6060

3. Abrindo um navegador em http://localhost:6060/pkg/github.com/aws/aws-xray-sdk-go/.