# Instrumentação
> Instrumentação manual para OpenTelemetry Go
---
LLMS index: [llms.txt](/llms.txt)
---
[Instrumentação](/docs/concepts/instrumentation/) é o ato de adicionar código de
observabilidade a uma aplicação por conta própria.
Se você estiver instrumentando uma aplicação, será necessário utilizar o SDK do
OpenTelemetry para sua linguagem. Você irá utilizar o SDK para inicializar o
OpenTelemetry e a API para instrumentar seu código. Isso passará a emitir dados
de telemetria da sua aplicação e de qualquer biblioteca que você tenha instalado
que também possua instrumentação.
Se você estiver instrumentando uma biblioteca, instale apenas o pacote da API do
OpenTelemetry para sua linguagem. Sua biblioteca não emitirá telemetria por
conta própria; ela só emitirá telemetria quando fizer parte de uma aplicação que
utiliza o SDK do OpenTelemetry. Para mais informações sobre a instrumentação de
bibliotecas, consulte a seção
[Bibliotecas](/docs/concepts/instrumentation/libraries/).
Para mais informações sobre a API e o SDK do OpenTelemetry, consulte a
[especificação](/docs/specs/otel/).
{{__hugo_ctx/}}
## Configuração {#setup}
## Rastros {#traces}
### Inicializando um Tracer {#getting-a-tracer}
Para criar trechos, você precisará obter ou inicializar um Tracer primeiro.
Certifique-se que os seguintes pacotes Go foram instalados corretamente:
```sh
go get go.opentelemetry.io/otel \
go.opentelemetry.io/otel/trace \
go.opentelemetry.io/otel/sdk \
```
Em seguida, inicialize um exporter, recursos, Tracer provider e finalmente o
rastreador.
```go
package app
import (
"context"
"fmt"
"log"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/sdk/resource"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
"go.opentelemetry.io/otel/trace"
)
var tracer trace.Tracer
func newExporter(ctx context.Context) /* (someExporter.Exporter, error) */ {
// Seu Exporter de preferência: console, jaeger, zipkin, OTLP, etc.
}
func newTracerProvider(exp sdktrace.SpanExporter) *sdktrace.TracerProvider {
// Certifique-se de que os recursos padrão do SDK e o nome do serviço estão definidos.
r, err := resource.Merge(
resource.Default(),
resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceName("ServicoExemplo"),
),
)
if err != nil {
panic(err)
}
return sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exp),
sdktrace.WithResource(r),
)
}
func main() {
ctx := context.Background()
exp, err := newExporter(ctx)
if err != nil {
log.Fatalf("falha ao inicializar o exporter: %v", err)
}
// Crie um novo TracerProvider com o Processor de Trechos e o Exporter criado.
tp := newTracerProvider(exp)
// Lidamos com a finalização corretamente, evitando leaks.
defer func() { _ = tp.Shutdown(ctx) }()
otel.SetTracerProvider(tp)
// Finalmente, definimos o Tracer que será utilizado por este pacote.
tracer = tp.Tracer("example.io/package/name")
}
```
Agora você pode acessar `tracer` para instrumentar manualmente o seu código.
Importante
Se você estiver adicionando trechos manuais em conjunto com a
[instrumentação sem código para Go](/docs/zero-code/go) baseada em eBPF, como o
[OBI](/docs/zero-code/obi), não defina um Tracer Provider global. Consulte a
documentação [Auto SDK](/docs/zero-code/go/autosdk) para mais informações.
Caso você esteja instrumentando uma biblioteca, pule esta etapa.
Para habilitar [métricas](/docs/concepts/signals/metrics/) em sua aplicação,
você precisará de um
[`MeterProvider`](/docs/concepts/signals/metrics/#meter-provider) inicializado,
que permitirá que você crie um [`Meter`](/docs/concepts/signals/metrics/#meter).
Caso um `MeterProvider` não seja inicializado, a API de métricas do
OpenTelemetry irá utilizar uma implementação sem operação e não irá gerar dados
de métricas. Sendo assim, é necessário que o código-fonte da aplicação seja
modificado para incluir a inicialização do SDK utilizando os seguintes pacotes:
- [`go.opentelemetry.io/otel`][]
- [`go.opentelemetry.io/otel/sdk/metric`][]
- [`go.opentelemetry.io/otel/sdk/resource`][]
- [`go.opentelemetry.io/otel/exporters/stdout/stdoutmetric`][]
Certifique-se que os seguintes pacotes Go foram instalados corretamente:
```sh
go get go.opentelemetry.io/otel \
go.opentelemetry.io/otel/exporters/stdout/stdoutmetric \
go.opentelemetry.io/otel/sdk \
go.opentelemetry.io/otel/sdk/metric
```
Em seguida, inicialize um `Resource`, `Metrics Exporter` e um `Meter Provider`:
```go
package main
import (
"context"
"log"
"time"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/stdout/stdoutmetric"
"go.opentelemetry.io/otel/sdk/metric"
"go.opentelemetry.io/otel/sdk/resource"
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
)
func main() {
// Crie um 'Resource'.
res, err := newResource()
if err != nil {
panic(err)
}
// Inicialize um Meter Provider.
// Você poderá passar a instância diretamente para o seu código instrumentado, caso
// o mesmo aceite uma instância do MeterProvider.
meterProvider, err := newMeterProvider(res)
if err != nil {
panic(err)
}
// Lidamos com a finalização corretamente, evitando vazamentos.
defer func() {
if err := meterProvider.Shutdown(context.Background()); err != nil {
log.Println(err)
}
}()
// Registre o MeterProvider globalmente, permitindo a utilização via otel.Meter
// e o acesso utilizando otel.GetMeterProvider.
// A maioria das bibliotecas de instrumentação utilizam o MeterProvider global como padrão.
// Caso o MeterProvider global não esteja definido, será utilizada uma implementação sem operação
// e não irá gerar dados de métricas.
otel.SetMeterProvider(meterProvider)
}
func newResource() (*resource.Resource, error) {
return resource.Merge(
resource.Default(),
resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceName("meu-servico"),
semconv.ServiceVersion("0.1.0"),
),
)
}
func newMeterProvider(res *resource.Resource) (*metric.MeterProvider, error) {
metricExporter, err := stdoutmetric.New()
if err != nil {
return nil, err
}
meterProvider := metric.NewMeterProvider(
metric.WithResource(res),
metric.WithReader(metric.NewPeriodicReader(metricExporter,
// O valor padrão é 1m. Definimos em 3s para propósitos de demonstração.
metric.WithInterval(3*time.Second))),
)
return meterProvider, nil
}
```
Agora que o `MeterProvider` está configurado, podemos obter um `Meter`.
### Obtendo um Meter {#acquiring-a-meter}
Qualquer ponto da sua aplicação que possua código instrumentado poderá invocar o
método [`otel.Meter`](https://pkg.go.dev/go.opentelemetry.io/otel#Meter) para
obter um `Meter`. Por exemplo:
```go
import "go.opentelemetry.io/otel"
var meter = otel.Meter("example.io/package/name")
```
### Instrumentos síncronos e assíncronos {#synchronous-and-asynchronous-instruments}
Os instrumentos do OpenTelemetry podem ser síncronos ou assíncronos
(observáveis).
Os instrumentos síncronos fazem uma medição quando são chamados. A medição é
realizada como uma chamada de método durante a execução da aplicação, assim como
qualquer outra chamada de método. Periodicamente, a agregação dessas medições é
exportada por um `Exporter` configurado. Como as medições são desacopladas da
exportação dos valores medidos, um ciclo de exportação pode conter zero ou
várias medições agregadas.
Os instrumentos assíncronos, por outro lado, fornecem uma medição a partir de
uma solicitação do SDK. Quando o SDK realiza a exportação, uma função de retorno
fornecida ao instrumento de medição no momento de sua criação é invocada. Esta
função de retorno fornece ao SDK uma medição, que é imediatamente exportada.
Todas as medições em instrumentos assíncronos são realizadas uma vez por cada
ciclo de exportação.
Os instrumentos assíncronos podem ser úteis em diversas circunstâncias, como:
- Quando a atualização de um contador não é computacionalmente barata e você não
deseja que o processo em execução aguarde pela medição.
- Quando medições precisam acontecer em frequências não-relacionadas ao tempo de
execução da aplicação (ou seja, não podem ser medidas com precisão ao serem
vinculadas ao ciclo de vida de uma operação).
- Quando não há um registro de data/hora conhecidos para um valor de medição.
Em casos como estes, muitas vezes é melhor realizar a medição de um valor
cumulativo diretamente, em vez de agregar uma série de deltas no
pós-processamento (como ocorre no exemplo síncrono).
### Utilizando Contadores (Counters) {#using-counters}
Contadores (Counters) podem ser utilizados para medir valores incrementais e
não-negativos.
Por exemplo, aqui está como seria possível reportar o número de chamadas em um
servidor HTTP:
```go
import (
"net/http"
"go.opentelemetry.io/otel/metric"
)
func init() {
apiCounter, err := meter.Int64Counter(
"api.counter",
metric.WithDescription("Número de chamadas na API."),
metric.WithUnit("{call}"),
)
if err != nil {
panic(err)
}
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
apiCounter.Add(r.Context(), 1)
// implementação da chamada da API
})
}
```
### Utilizando Contadores UpDown (UpDown Counters) {#using-updown-counters}
Os Contadores UpDown (UpDown Counters) podem incrementar e decrementar,
permitindo que você meça um valor cumulativo que aumenta ou diminui.
Por exemplo, aqui está como é possível reportar o número de itens de uma
coleção:
```go
import (
"context"
"go.opentelemetry.io/otel/metric"
)
var itemsCounter metric.Int64UpDownCounter
func init() {
var err error
itemsCounter, err = meter.Int64UpDownCounter(
"items.counter",
metric.WithDescription("Número de itens."),
metric.WithUnit("{item}"),
)
if err != nil {
panic(err)
}
}
func addItem() {
// código que insere um item na coleção
itemsCounter.Add(context.Background(), 1)
}
func removeItem() {
// código que remove um item da coleção
itemsCounter.Add(context.Background(), -1)
}
```
### Utilizando Medidores (Gauges) {#using-gauges}
Medidores (Gauges) são utilizados para medir quando ocorrem mudanças em valores
não-aditivos.
Por exemplo, veja como é possível relatar a velocidade atual de um ventilador de
CPU:
```go
import (
"net/http"
"go.opentelemetry.io/otel/metric"
)
var fanSpeedSubscription chan int64
func init() {
speedGauge, err := meter.Int64Gauge(
"cpu.fan.speed",
metric.WithDescription("Velocidade atual de um ventilador de CPU"),
metric.WithUnit("RPM"),
)
if err != nil {
panic(err)
}
getCPUFanSpeed := func() int64 {
// Vamos gerar um valor aleatório para propósito de demonstração.
// Em uma aplicação do mundo real, substitua esta implementação para obter o real valor do ventilador de CPU.
return int64(1500 + rand.Intn(1000))
}
fanSpeedSubscription = make(chan int64, 1)
go func() {
defer close(fanSpeedSubscription)
for idx := 0; idx < 5; idx++ {
// Gauges síncronos são utilizados quando o ciclo de medição está
// relacionado a uma mudança externa.
time.Sleep(time.Duration(rand.Intn(3)) * time.Second)
fanSpeed := getCPUFanSpeed()
fanSpeedSubscription <- fanSpeed
}
}()
}
func recordFanSpeed() {
ctx := context.Background()
for fanSpeed := range fanSpeedSubscription {
speedGauge.Record(ctx, fanSpeed)
}
}
```
### Utilizando Histogramas (Histograms) {#using-histograms}
Histogramas (Histograms) são utilizados para medir a distribuição de valores ao
longo do tempo.
Por exemplo, veja como é possível reportar a distribuição de tempos de resposta
para um servidor HTTP:
```go
import (
"net/http"
"time"
"go.opentelemetry.io/otel/metric"
)
func init() {
histogram, err := meter.Float64Histogram(
"task.duration",
metric.WithDescription("Tempo de duração da execução da tarefa."),
metric.WithUnit("s"),
)
if err != nil {
panic(err)
}
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
// insira algum código na chamada da API
duration := time.Since(start)
histogram.Record(r.Context(), duration.Seconds())
})
}
```
### Utilizando Contadores (Assíncronos) Observáveis {#using-observable-async-counters}
Counters observáveis (Observable counters) podem ser utilizados para medir um
valor aditivo, não-negativo e monotonamente crescente.
Por exemplo, veja como é possível reportar o tempo de duração desde que a
aplicação foi iniciada:
```go
import (
"context"
"time"
"go.opentelemetry.io/otel/metric"
)
func init() {
start := time.Now()
if _, err := meter.Float64ObservableCounter(
"uptime",
metric.WithDescription("Tempo de duração desde o início da aplicação."),
metric.WithUnit("s"),
metric.WithFloat64Callback(func(_ context.Context, o metric.Float64Observer) error {
o.Observe(float64(time.Since(start).Seconds()))
return nil
}),
); err != nil {
panic(err)
}
}
```
### Utilizando Contadores UpDown (Assíncronos) Observáveis {#using-observable-async-updown-counters}
Contadores UpDown (Counters UpDown) observáveis podem incrementar e decrementar,
permitindo que você meça um valor cumulativo aditivo, não-negativo e
não-monotonamente crescente.
Por exemplo, veja como é possível reportar algumas métricas de banco de dados:
```go
import (
"context"
"database/sql"
"go.opentelemetry.io/otel/metric"
)
// registerDBMetrics registra métricas assíncronas para a base de dados fornecida.
// Certifique-se de desfazer o registro da métrica `metric.Registration` antes de encerrar a conexão com o banco de dados.
func registerDBMetrics(db *sql.DB, meter metric.Meter, poolName string) (metric.Registration, error) {
max, err := meter.Int64ObservableUpDownCounter(
"db.client.connections.max",
metric.WithDescription("O número máximo de conexões abertas permitidas."),
metric.WithUnit("{connection}"),
)
if err != nil {
return nil, err
}
waitTime, err := meter.Int64ObservableUpDownCounter(
"db.client.connections.wait_time",
metric.WithDescription("O tempo que levou para obter uma conexão aberta da pool."),
metric.WithUnit("ms"),
)
if err != nil {
return nil, err
}
reg, err := meter.RegisterCallback(
func(_ context.Context, o metric.Observer) error {
stats := db.Stats()
o.ObserveInt64(max, int64(stats.MaxOpenConnections))
o.ObserveInt64(waitTime, int64(stats.WaitDuration))
return nil
},
max,
waitTime,
)
if err != nil {
return nil, err
}
return reg, nil
}
```
### Utilizando Medidores (Assíncronos) Observáveis {#using-observable-async-gauges}
Medidores (Gauges) observáveis devem ser utilizados para medir valores
não-aditivos.
Por exemplo, veja como é possível reportar o uso de memória dos objetos _heap_
utilizados na aplicação:
```go
import (
"context"
"runtime"
"go.opentelemetry.io/otel/metric"
)
func init() {
if _, err := meter.Int64ObservableGauge(
"memory.heap",
metric.WithDescription(
"Uso de memória dos objetos heap alocados.",
),
metric.WithUnit("By"),
metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
var m runtime.MemStats
runtime.ReadMemStats(&m)
o.Observe(int64(m.HeapAlloc))
return nil
}),
); err != nil {
panic(err)
}
}
```
### Adicionando atributos {#adding-attributes}
É possível adicionar atributos utilizando as opções
[`WithAttributeSet`](https://pkg.go.dev/go.opentelemetry.io/otel/metric#WithAttributeSet)
ou
[`WithAttributes`](https://pkg.go.dev/go.opentelemetry.io/otel/metric#WithAttributes).
```go
import (
"net/http"
"go.opentelemetry.io/otel/metric"
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
)
func init() {
apiCounter, err := meter.Int64UpDownCounter(
"api.finished.counter",
metric.WithDescription("Número de chamadas da API finalizadas."),
metric.WithUnit("{call}"),
)
if err != nil {
panic(err)
}
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
// insira algum código na chamada da API e defina o status HTTP de resposta
apiCounter.Add(r.Context(), 1,
metric.WithAttributes(semconv.HTTPResponseStatusCode(statusCode)))
})
}
```
### Registrando Views {#registering-views}
Uma _view_ oferece aos usuários do SDK a flexibilidade de personalizar a emissão
das métricas pelo SDK. Você pode personalizar quais instrumentos de métricas
devem ser processados ou ignorados. Você também pode personalizar a agregação e
quais atributos você deseja relatar nas métricas.
Cada instrumento possui sua _view_ padrão, que mantém o nome, descrição e
atributos originais, e tem uma agregação padrão baseada no tipo do instrumento.
Quando uma _view_ registrada corresponde a um instrumento, a _view_ padrão é
substituída pela _view_ registrada. _Views_ registradas adicionais que
correspondem ao instrumento são aditivas, resultando em múltiplas métricas
exportadas para o instrumento.
É possível utilizar o método
[`NewView`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#NewView) para
criar uma _view_ e registrá-la utilizando a opção
[`WithView`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#WithView).
Por exemplo, veja como é possível criar uma _view_ que renomeia o instrumento
`latency` da versão `v0.34.0` da biblioteca de instrumentação `http` para
`request.latency`:
```go
view := metric.NewView(metric.Instrument{
Name: "latency",
Scope: instrumentation.Scope{
Name: "http",
Version: "0.34.0",
},
}, metric.Stream{Name: "request.latency"})
meterProvider := metric.NewMeterProvider(
metric.WithView(view),
)
```
Em outro exemplo, veja como é possível criar uma _view_ que faz com que o
instrumento `latency` da biblioteca de instrumentação `http` seja reportado como
um histograma exponencial:
```go
view := metric.NewView(
metric.Instrument{
Name: "latency",
Scope: instrumentation.Scope{Name: "http"},
},
metric.Stream{
Aggregation: metric.AggregationBase2ExponentialHistogram{
MaxSize: 160,
MaxScale: 20,
},
},
)
meterProvider := metric.NewMeterProvider(
metric.WithView(view),
)
```
O SDK filtra métricas e atributos antes de exportar as métricas. Você pode
utilizar _views_ para reduzir o uso de memória de métricas de alta cardinalidade
ou descartar atributos que possam conter dados sensíveis.
No exemplo a seguir, criamos uma _view_ que descarta o instrumento `latency` da
biblioteca de instrumentação `http`:
```go
view := metric.NewView(
metric.Instrument{
Name: "latency",
Scope: instrumentation.Scope{Name: "http"},
},
metric.Stream{Aggregation: metric.AggregationDrop{}},
)
meterProvider := metric.NewMeterProvider(
metric.WithView(view),
)
```
No exemplo a seguir, criamos uma _view_ que remove o atributo
`http.request.method` registrado pelo instrumento `latency` da biblioteca de
instrumentação `http`:
```go
view := metric.NewView(
metric.Instrument{
Name: "latency",
Scope: instrumentation.Scope{Name: "http"},
},
metric.Stream{AttributeFilter: attribute.NewDenyKeysFilter("http.request.method")},
)
meterProvider := metric.NewMeterProvider(
metric.WithView(view),
)
```
O atributo `Name` suporta correspondência de padrão curinga. O curinga `*` é
reconhecido como correspondendo a zero ou mais caracteres, e o curinga `?` é
reconhecido como correspondendo exatamente a um caractere. Por exemplo, um
padrão de `*` corresponde a todos os nomes de instrumentos.
No exemplo a seguir, mostramos como criar uma _view_ que define a unidade como
milissegundos para qualquer instrumento com um sufixo de nome `.ms`:
```go
view := metric.NewView(
metric.Instrument{Name: "*.ms"},
metric.Stream{Unit: "ms"},
)
meterProvider := metric.NewMeterProvider(
metric.WithView(view),
)
```
O método `NewView` fornece uma maneira conveniente de criar _views_. Caso o
método `NewView` não forneça as funcionalidades que você precisa, é possível
criar uma _[View](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#View)_
personalizada.
No exemplo a seguir, veja como criar uma _view_ que faz o uso de expressões
regulares para garantir que todos os nomes de fluxo de dados tenham um sufixo
das unidades que utiliza:
```go
re := regexp.MustCompile(`[._](ms|byte)$`)
var view metric.View = func(i metric.Instrument) (metric.Stream, bool) {
// Em uma função de View personalizada, é necessário copiar de maneira explícita
// o nome, descrição e unidade.
s := metric.Stream{Name: i.Name, Description: i.Description, Unit: i.Unit}
// Qualquer instrumento que não tenha um sufixo de unidade de medida definido, mas tenha
// uma unidade dimensional definida, terá seu nome atualizado com um sufixo de unidade de medida.
if re.MatchString(i.Name) {
return s, false
}
switch i.Unit {
case "ms":
s.Name += ".ms"
case "By":
s.Name += ".byte"
default:
return s, false
}
return s, true
}
meterProvider := metric.NewMeterProvider(
metric.WithView(view),
)
```
## Logs
Logs são distintos de métricas e rastros, pois **não há uma API de logs do
OpenTelemetry voltada para o usuário**. Em vez disso, existem ferramentas que
integram pacotes de logs populares existentes (como slog, logrus, zap, logr) aos
logs do ecossistema OpenTelemetry. Para a justificativa por trás dessa decisão
de design, consulte a [especificação de Logs](/docs/specs/otel/logs/).
Os dois _workflows_ discutidos abaixo atendem a diferentes requisitos de
aplicação.
### Direto para o Collector {#direct-to-collector}
**Estado**: [Experimental](/docs/specs/otel/document-status/)
No _workflow_ direto para o collector, os logs são emitidos diretamente da
aplicação para o Collector utilizando um protocolo de rede (por exemplo, OTLP).
Este _workflow_ é simples de configurar, pois não requer componentes adicionais
de encaminhamento de logs, permitindo que uma aplicação emita logs estruturados
e que estejam nos conformes do [modelo de dados de logs][log data model]. No
entanto, a sobrecarga necessária para que as aplicações enfileirem e exportem
logs para um local de rede pode não ser adequada para todas as aplicações.
Para utilizar este _workflow_:
- Configurar o [SDK de Logs](#logs-sdk) do OpenTelemetry para exportar registros
de logs para o destino desejado (o [OpenTelemetry
Collector][opentelemetry collector] ou outro).
- Utilizar um [Log Bridge](#log-bridge) apropriado.
#### SDK de Logs {#logs-sdk}
O SDK de Logs define como os logs são processados ao utilizar o _workflow_
[Direto para o Collector](#direct-to-collector). Nenhum SDK de logs é necessário
ao utilizar o _workflow_ de [encaminhamento de logs](#via-file-or-stdout).
Uma configuração típica do SDK de logs instala um Processor de logs em lote com
um Exporter OTLP.
Para habilitar [logs](/docs/concepts/signals/logs/) em sua aplicação, você
precisará ter um
[`LoggerProvider`](/docs/concepts/signals/logs/#logger-provider) inicializado,
que permitirá que você utilize um [Log Bridge](#log-bridge).
Caso um `LoggerProvider` não seja criado, a API de Logs do OpenTelemetry irá
utilizar uma implementação sem operação e dados de logs não serão gerados. Sendo
assim, é necessário que o código-fonte da aplicação seja modificado para incluir
a inicialização do SDK utilizando os seguintes pacotes:
- [`go.opentelemetry.io/otel`][]
- [`go.opentelemetry.io/otel/sdk/log`][]
- [`go.opentelemetry.io/otel/sdk/resource`][]
- [`go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp`][]
Certifique-se que os seguintes pacotes Go foram instalados corretamente:
```sh
go get go.opentelemetry.io/otel \
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp \
go.opentelemetry.io/otel/sdk \
go.opentelemetry.io/otel/sdk/log
```
Em seguida, inicialize o `LoggerProvider`:
```go
package main
import (
"context"
"fmt"
"go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp"
"go.opentelemetry.io/otel/log/global"
"go.opentelemetry.io/otel/sdk/log"
"go.opentelemetry.io/otel/sdk/resource"
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
)
func main() {
ctx := context.Background()
// Crie um 'Resource'.
res, err := newResource()
if err != nil {
panic(err)
}
// Crie um 'LoggerProvider'.
// Você pode passar essa instância diretamente ao criar um Log Bridge.
loggerProvider, err := newLoggerProvider(ctx, res)
if err != nil {
panic(err)
}
// Lidamos com a finalização corretamente, evitando vazamentos.
defer func() {
if err := loggerProvider.Shutdown(ctx); err != nil {
fmt.Println(err)
}
}()
// Registre o LoggerProvider globalmente, permitindo que seja acessado via global.LoggerProvider.
// A maioria dos Log Bridges utilizam o LoggerProvider global como padrão.
// Caso o LoggerProvider global não esteja definido, será utilizada uma implementação sem operação
// e dados de logs não serão gerados.
global.SetLoggerProvider(loggerProvider)
}
func newResource() (*resource.Resource, error) {
return resource.Merge(
resource.Default(),
resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceName("meu-servico"),
semconv.ServiceVersion("0.1.0"),
),
)
}
func newLoggerProvider(ctx context.Context, res *resource.Resource) (*log.LoggerProvider, error) {
exporter, err := otlploghttp.New(ctx)
if err != nil {
return nil, err
}
processor := log.NewBatchProcessor(exporter)
provider := log.NewLoggerProvider(
log.WithResource(res),
log.WithProcessor(processor),
)
return provider, nil
}
```
Agora que o `LoggerProvider` está configurado, é possível utilizá-lo para
configurar um [Log Bridge](#log-bridge).
#### Log Bridge {#log-bridge}
Um Log Bridge é um componente que conecta logs de um pacote existente ao
[SDK de Logs](#logs-sdk) do OpenTelemetry, utilizando a [Logs Bridge
API][logs bridge API].
Uma lista completa contendo os _log bridges_ disponíveis pode ser encontrada no
[registro do OpenTelemetry](/ecosystem/registry/?language=go&component=log-bridge).
Cada pacote do Log Bridge deve possuir uma documentação contendo as suas
instruções de instalação e configuração, e um exemplo.
### Através de arquivos ou stdout {#via-file-or-stdout}
No _workflow_ utilizado em arquivos ou _stdout_, os logs são gravados em
arquivos ou na saída padrão da aplicação. Outro componente (por exemplo,
FluentBit) é responsável por ler/acompanhar os logs, convertê-los para um
formato mais estruturado e encaminhá-los para um destino, como o Collector. Este
_workflow_ pode ser preferível em situações onde os requisitos da aplicação não
permitem a sobrecarga adicional do
[Direto para o Collector](#direct-to-collector). No entanto, é requisito que
todos os campos de log necessários sejam codificados nos logs, e que o
componente responsável pela leitura realize a conversão para o [modelo de dados
de logs][log data model]. A instalação e configuração dos componentes de
encaminhamento de logs está fora do escopo deste documento.
## Próximas Etapas (#next-steps)
Você também vai querer configurar um Exporter apropriado para
[exportar seus dados de telemetria](/docs/languages/go/exporters) para um ou
mais backends de telemetria.
[opentelemetry specification]: /docs/specs/otel/
[trace semantic conventions]: /docs/specs/semconv/general/trace/
[instrumentation library]: ../libraries/
[opentelemetry collector]:
https://github.com/open-telemetry/opentelemetry-collector
[logs bridge API]: /docs/specs/otel/logs/api/
[log data model]: /docs/specs/otel/logs/data-model
[`go.opentelemetry.io/otel`]: https://pkg.go.dev/go.opentelemetry.io/otel
[`go.opentelemetry.io/otel/exporters/stdout/stdoutmetric`]:
https://pkg.go.dev/go.opentelemetry.io/otel/exporters/stdout/stdoutmetric
[`go.opentelemetry.io/otel/metric`]:
https://pkg.go.dev/go.opentelemetry.io/otel/metric
[`go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp`]:
https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp
[`go.opentelemetry.io/otel/sdk/log`]:
https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log
[`go.opentelemetry.io/otel/sdk/metric`]:
https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric
[`go.opentelemetry.io/otel/sdk/resource`]:
https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource