@stone-ton/otlp

A biblioteca @stone-ton/otlp é uma ferramenta que oferece suporte para instrumentar o rastreamento de código usando o OpenTelemetry quando a variável de ambiente OTLP é definida como true e a variável de ambiente OTLP_TRACE_URL é configurada corretamente.

Instalação

Para utilizar a biblioteca @stone-ton/otlp, você precisa primeiro instalá-la em seu projeto. Isso pode ser feito através do gerenciador de pacotes npm ou yarn, dependendo de sua preferência:

npm install @stone-ton/otlp

Configuração

Antes de começar a usar a biblioteca, certifique-se de definir as variáveis de ambiente necessárias:

• OTLP: Deve ser definido como true para habilitar o rastreamento com OpenTelemetry.
• OTLP_TRACE_URL: Deve ser definido com a URL do servidor OpenTelemetry Collector, por exemplo, localhost:4318.

Uso

Após a instalação e configuração da biblioteca, você pode começar a usar o objeto tracer que ela expõe para instrumentar seu código para rastreamento.

import { SpanStatusCode, SpanKind } from '@opentelemetry/api'
import { SemanticAttributes, DbSystemValues } from '@opentelemetry/semantic-conventions'
import { tracer } from '@stone-ton/otlp'
import { hrTime } from '@opentelemetry/core'

const result = await tracer.startActiveSpan('dynamoGet',
  {
    kind: SpanKind.CLIENT,
    startTime: hrTime(),
  },
  async (span) => {
    try {
      span.setAttributes({
        [SemanticAttributes.DB_SYSTEM]: DbSystemValues.DYNAMODB,
        [SemanticAttributes.DB_OPERATION]: 'get',
        [SemanticAttributes.AWS_DYNAMODB_TABLE_NAMES]: [params.TableName],
      })

      const { Item } = await dynamodb.get(params).promise()

      return Item as (T | undefined)
    } catch (error: any) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error.message,
      })
      span.setAttribute(SemanticAttributes.DB_STATEMENT, JSON.stringify(params))

      throw error
    } finally {
      span.end(hrTime())
    }
  },
)

No código acima, foram feitas as seguintes modificações:

1. tracer.startActiveSpan('dynamoGet', { kind: SpanKind.CLIENT }, async (span) => { ... }):

   O método startActiveSpan é uma função fornecida pela biblioteca @stone-ton/otlp que cria um novo span ativo. Um span é uma unidade de rastreamento que representa um período de tempo em uma operação. O primeiro argumento 'dynamoGet' é o nome atribuído ao span, que identifica a operação sendo rastreada. O segundo argumento é um objeto que configura o tipo do span, chamado de kind. No exemplo, SpanKind.CLIENT indica que o span é do tipo "cliente", ou seja, ele representa uma chamada a um serviço externo, como um banco de dados ou API.

2. span.setAttributes({ ... }):

   O método setAttributes é usado para adicionar atributos ao span. Atributos são metadados associados ao span que fornecem informações adicionais sobre a operação. No exemplo, diversos atributos específicos para rastreamento de banco de dados são definidos, como o sistema de banco de dados, a operação sendo executada e o nome da tabela. Isso ajuda a enriquecer o contexto do span com informações relevantes.

3. span.setStatus({ ... }):

   O método setStatus é usado para definir o status do span. No exemplo, é usado para indicar que ocorreu um erro durante a execução da operação. O status do span pode ser usado para sinalizar informações importantes, como códigos de erro e mensagens descritivas.

4. span.end():

   O método end é usado para finalizar o span. Quando um span é finalizado, ele é encerrado e as informações sobre o tempo decorrido e quaisquer metadados associados são registrados. Isso é importante para garantir que os registros de rastreamento sejam precisos e abrangentes.

O código fornecido utiliza essas funcionalidades do OpenTelemetry por meio da biblioteca @stone-ton/otlp para instrumentar o rastreamento de uma operação de obtenção de dados de um banco de dados DynamoDB. Ao usar spans, atributos, status e o encerramento correto dos spans, você cria um rastreamento eficiente e detalhado das operações em seu código, o que é extremamente útil para análise, depuração e monitoramento do desempenho do sistema.

Lembre-se de que o rastreamento será ativado apenas se as variáveis de ambiente OTLP e OTLP_TRACE_URL estiverem corretamente configuradas.