npm package: @stone-ton/otlp
Description: Lib para centralizar configuração do opentelemetry
Author: Emerson Katsumi Matsumoto
Latest version: 0.0.7

# @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:

```bash
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.

```javascript
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.