> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação do OpenTelemetry no Rust

Esta página mostra como enviar traces e métricas da sua aplicação Rust para o AppSignal com o OpenTelemetry. Ao final, os spans que sua aplicação cria com o crate `tracing` aparecem na página "Performance > Traces" no AppSignal.

Certifique-se de [instalar o AppSignal collector](https://docs.appsignal.com/opentelemetry/installation.md) antes de prosseguir com estas instruções.

## Instale os crates do OpenTelemetry

Use o Cargo para adicionar às dependências da sua aplicação o SDK do OpenTelemetry, o exporter OTLP, a integração com `tracing` e os crates que a configuração abaixo usa:

```sh Shell theme={null}
cargo add opentelemetry@0.28 --features trace,metrics
cargo add opentelemetry_sdk@0.28 --features trace,metrics
cargo add opentelemetry-otlp@0.28 --features http-proto,reqwest-blocking-client,reqwest-rustls,metrics
cargo add tracing@0.1 tracing-opentelemetry@0.29
cargo add tracing-subscriber@0.3 --features env-filter
cargo add nix@0.23
```

Quais versões funcionam juntas, e o que alguns desses crates e features fazem:

* **`tracing-opentelemetry`**: sua versão deve corresponder à dos crates do OpenTelemetry. A versão 0.29 do `tracing-opentelemetry` funciona com a versão 0.28 de `opentelemetry`, `opentelemetry_sdk` e `opentelemetry-otlp`. Se você atualizar um, atualize o outro para uma versão correspondente.
* **`reqwest-rustls`**: esta feature permite que o exporter envie dados para URLs de collector com `https://`, como um [collector hospedado](https://docs.appsignal.com/collector/hosted-vs-self-hosted.md).
* **`nix`**: obtém o hostname da máquina em que sua aplicação roda, que a configuração reporta como `host.name`.
* **`env-filter`**: esta feature do `tracing-subscriber` permite escolher quais spans reportar com a variável de ambiente `RUST_LOG`.

## Configure o OpenTelemetry na sua aplicação

Adicione este módulo `appsignal.rs` ao diretório `src` da sua aplicação, ao lado de `main.rs`. Ele configura os exporters que enviam traces e métricas para o AppSignal collector, e os atributos que o AppSignal usa para reconhecer sua aplicação.

Antes de executá-lo, atualize estes valores no início de `initialize_opentelemetry`:

* `name`: o nome da sua aplicação no AppSignal.
* `environment`: o ambiente em que sua aplicação roda, como `development`, `staging` ou `production`.
* `push_api_key`: a [Push API key](https://docs.appsignal.com/appsignal/terminology.md#push-api-key) da sua organização, que você encontra na [página de configurações Push & deploy](https://appsignal.com/redirect-to/app?to=info).
* `endpoint`: mantenha `http://localhost:8099` se o collector roda na mesma máquina que sua aplicação. Caso contrário, use o endereço do seu collector. Para um collector hospedado, abra a página ["Hosted Collector"](https://appsignal.com/redirect-to/organization?to=admin/hosted_collectors) nas configurações da sua organização, abra seu collector e copie a "Collector URL" dele. Se a lista estiver vazia, crie um collector lá primeiro.

```rust Rust theme={null}
use opentelemetry::{global, trace::TracerProvider as _, KeyValue};
use opentelemetry_otlp::WithExportConfig;
use opentelemetry_sdk::{
    metrics::{PeriodicReader, SdkMeterProvider, Temporality},
    propagation::TraceContextPropagator,
    trace::SdkTracerProvider,
    Resource,
};
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};

pub struct Telemetry {
    tracer_provider: SdkTracerProvider,
    meter_provider: SdkMeterProvider,
}

impl Telemetry {
    // Send the remaining traces and metrics to the collector and stop the exporters.
    pub fn shutdown(self) {
        let _ = self.tracer_provider.shutdown();
        let _ = self.meter_provider.shutdown();
    }
}

pub fn initialize_opentelemetry(service_name: &str) -> Telemetry {
    // Replace these values with your AppSignal application name, environment
    // and push API key. These are used by the resource attributes configuration below.
    let name = "My app";
    let push_api_key = "0000-0000-0000-0000";
    let environment = "production";

    // Replace `http://localhost:8099` with the address of your AppSignal collector
    // if it's running on another host.
    let endpoint = "http://localhost:8099";

    // The version from your application's `Cargo.toml`, set when it's compiled.
    let revision = env!("CARGO_PKG_VERSION");

    let mut hostname_buffer = [0u8; 512];
    let hostname = nix::unistd::gethostname(&mut hostname_buffer)
        .map(|hostname| hostname.to_string_lossy().to_string())
        .unwrap_or_else(|_| "unknown".to_string());

    let app_path = std::env::current_dir()
        .map(|path| path.display().to_string())
        .unwrap_or_default();

    let resource = Resource::builder()
        // Customize the service name
        .with_service_name(service_name.to_string())
        .with_attributes([
            KeyValue::new("appsignal.config.name", name),
            KeyValue::new("appsignal.config.environment", environment),
            KeyValue::new("appsignal.config.push_api_key", push_api_key),
            KeyValue::new("appsignal.config.revision", revision),
            KeyValue::new("appsignal.config.language_integration", "rust"),
            KeyValue::new("appsignal.config.app_path", app_path),
            KeyValue::new("host.name", hostname),
        ])
        .build();

    global::set_text_map_propagator(TraceContextPropagator::new());

    let span_exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_http()
        .with_endpoint(format!("{endpoint}/v1/traces"))
        .build()
        .expect("Failed to create the span exporter");
    let tracer_provider = SdkTracerProvider::builder()
        .with_batch_exporter(span_exporter)
        .with_resource(resource.clone())
        .build();
    global::set_tracer_provider(tracer_provider.clone());

    let metric_exporter = opentelemetry_otlp::MetricExporter::builder()
        .with_http()
        .with_endpoint(format!("{endpoint}/v1/metrics"))
        .with_temporality(Temporality::Delta)
        .build()
        .expect("Failed to create the metric exporter");
    let meter_provider = SdkMeterProvider::builder()
        .with_reader(PeriodicReader::builder(metric_exporter).build())
        .with_resource(resource)
        .build();
    global::set_meter_provider(meter_provider.clone());

    // Report the spans created with the `tracing` crate to OpenTelemetry, and
    // print your application's logs to the console.
    // Unless the `RUST_LOG` environment variable is set, the filter keeps spans
    // and logs at the `info` level and above, and only warnings and errors from
    // the OpenTelemetry crates themselves.
    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| {
        EnvFilter::new("info,opentelemetry=warn,opentelemetry_sdk=warn,opentelemetry_otlp=warn")
    });
    let otel_layer = tracing_opentelemetry::layer()
        .with_tracer(tracer_provider.tracer(service_name.to_string()));
    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer())
        .with(otel_layer)
        .init();

    Telemetry {
        tracer_provider,
        meter_provider,
    }
}
```

O código reporta a versão da sua aplicação definida no `Cargo.toml` como a [revision](https://docs.appsignal.com/opentelemetry/configuration/options.md#app-revision). O AppSignal usa a revision para criar um deploy marker sempre que você faz o deploy de uma nova versão. Uma revision pode ser um número de versão ou o SHA de um commit do Git.

O Cargo adiciona a versão ao binário quando compila sua aplicação. Assim, a revision é definida mesmo quando você faz o build em um serviço de CI, como o GitHub Actions, e executa o binário sem um repositório Git.

Incremente a versão no `Cargo.toml` a cada release, por exemplo quando você cria uma release no GitHub. Assim, cada deploy recebe seu próprio deploy marker.

## Inicie sua aplicação com o OpenTelemetry

Chame a função `initialize_opentelemetry` no início da função `main` da sua aplicação, para que os spans criados durante a inicialização também sejam reportados. Passe para ela o nome do serviço que está sendo monitorado. O AppSignal agrupa traces por [nome do serviço](https://docs.appsignal.com/opentelemetry/configuration/options.md#service-name), então escolha um nome que descreva esta parte da sua aplicação, como "Web server" ou "Background worker".

Antes que sua aplicação termine, chame `shutdown` para enviar os traces e métricas restantes ao AppSignal collector.

O exemplo abaixo usa o runtime Tokio. Se sua aplicação ainda não usa o Tokio, adicione-o com `cargo add tokio@1 --features full`.

O módulo `appsignal.rs` também imprime os logs da sua aplicação no console. Se sua aplicação já configura o logging com `tracing_subscriber`, por exemplo com `tracing_subscriber::fmt::init()`, remova essa chamada. O `tracing_subscriber` só pode ser configurado uma vez, então sua aplicação entra em panic na inicialização se ambos forem executados.

```rust Rust theme={null}
mod appsignal;

#[tokio::main]
async fn main() {
    // Set the name of the service that is being monitored. A common choice is the
    // name of the framework used. This is used to group traces and metrics in AppSignal.
    let telemetry = appsignal::initialize_opentelemetry("My service name");

    // Start your application here

    telemetry.shutdown();
}
```

Se sua aplicação é um servidor web, ela geralmente roda até receber um sinal de parada, como `SIGTERM` durante um deploy. Faça com que ela seja encerrada de forma graciosa ao receber um, para que o servidor pare, `main` continue e a chamada a `shutdown` seja executada. Por exemplo, use `with_graceful_shutdown` no axum. Sem um encerramento gracioso, sua aplicação termina antes de chamar `shutdown`, e os traces e métricas que ela ainda não enviou são perdidos.

## Crie spans com o crate tracing

O módulo `appsignal.rs` reporta ao AppSignal os spans que sua aplicação cria com o [crate `tracing`](https://docs.rs/tracing). Por exemplo, adicione o atributo `#[tracing::instrument]` a uma função para criar um span cada vez que ela é chamada. Cada chamada a esta função `checkout` cria um span chamado `checkout`:

```rust Rust theme={null}
#[tracing::instrument]
async fn checkout(order_id: u64) {
    // Your code here
}
```

O atributo `#[tracing::instrument]` cria spans no nível `info` por padrão. O módulo `appsignal.rs` reporta spans no nível `info` e acima, então esses spans chegam ao AppSignal sem configuração extra. Para reportar também spans `debug`, inicie sua aplicação com a variável de ambiente `RUST_LOG` definida como `debug`:

```sh Shell theme={null}
RUST_LOG=debug cargo run
```

## Teste o app!

Agora que todos os componentes estão conectados, inicie seu app e use-o para que ele crie spans, por exemplo enviando algumas requisições a ele. Depois, abra a página ["Performance > Traces"](https://appsignal.com/redirect-to/app?to=performance/traces) no AppSignal para ver os traces chegando.

> [!NOTE]
>
> Erros que você registra com o crate `tracing` não aparecem na página "Errors >
> Issue list". O crate `tracing-opentelemetry` os registra sem o atributo
> `exception.type`, que o AppSignal precisa para reportar um erro.

Se, depois de seguir nossas instruções de instalação, você ainda não vir dados no AppSignal, [avise-nos](mailto:support@appsignal.com?subject=OpenTelemetry%20issue) e te ajudaremos a finalizar a instalação do OpenTelemetry!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.