# Enviar dados

Source: https://instatus.com/help/pt-br/observability/send-logs

O Instatus recebe logs, traces e métricas via OpenTelemetry (OTLP sobre HTTPS). Há duas formas de conectar um app. Escolha uma.

| At a glance | Details |
| :-- | :-- |
| [Mais rápido](https://instatus.com/help/pt-br/observability/send-logs#opção-1-copie-um-prompt) | Copie um prompt para seu agente de programação |
| [Manualmente](https://instatus.com/help/pt-br/observability/send-logs#opção-2-configure-manualmente) | Escolha sua linguagem e cole o código |
| [Endpoint](https://instatus.com/help/pt-br/observability/send-logs#o-que-toda-requisição-precisa) | https://otel.instatus.com, mais dois cabeçalhos |
| [Teste](https://instatus.com/help/pt-br/observability/send-logs#envie-um-log-de-teste) | Uma requisição curl |
| [Nada aparece?](https://instatus.com/help/pt-br/observability/send-logs#solução-de-problemas) | Resolva os problemas mais comuns |

## Opção 1: Copie um prompt

O jeito mais rápido, se você usa um agente de programação como Claude Code, Cursor ou Copilot.

1. Abra **Observability** na sua página de status.
2. Em **Incluir**, marque o que deseja enviar: **Logs**, **Traces**, **Métricas**. Marque também **Dashboard inicial** se quiser dashboards prontos para seus serviços depois.
3. Clique em **Copiar prompt**.
4. Cole no seu agente de programação, no projeto do seu app.
5. Coloque sua [chave de API](#encontre-sua-chave-de-api) na variável de ambiente `INSTATUS_API_KEY` e rode o teste sugerido pelo agente.

![O cartão de configuração, com logs, traces e métricas para incluir e um botão para copiar o prompt](https://instatus.com/help/observability/setup.png)

O prompt instrui o agente a usar o SDK oficial do OpenTelemetry para sua linguagem, manter sua biblioteca de logs atual, ler a chave de uma variável de ambiente e nunca fazer commit dela. O ID da sua página já está nele.

## Opção 2: Configure manualmente

1. Abra **Observability** na sua página de status.
2. Clique em **Configurar manualmente**.
3. Escolha sua linguagem: Node.js, Python, Go, Java, .NET, Ruby, PHP ou o OpenTelemetry Collector.
4. Copie o comando de **Instalar** e rode, depois copie o código de **Configurar** para o seu app.
5. Defina a variável de ambiente `INSTATUS_API_KEY` com sua [chave de API](#encontre-sua-chave-de-api) e inicie seu app.

![Configuração manual com Node.js selecionado, mostrando o comando de instalação e o código de configuração](https://instatus.com/help/observability/setup-by-hand.png)

O código no painel já vem com o ID da sua página preenchido. Os mesmos exemplos estão abaixo, se preferir copiar daqui.

## O que toda requisição precisa

| O quê          | Valor                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Endpoint      | `https://otel.instatus.com`. Logs vão para `/v1/logs`, traces para `/v1/traces` e métricas para `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, com a chave de um proprietário, admin ou editor da página.                    |
| `X-Instatus-Site-Id` | O ID da página de status a que os dados pertencem.                                                |
| Protocolo      | OTLP sobre HTTP, em protobuf ou JSON. Se o seu SDK usa gRPC por padrão, mude para HTTP.          |

> Sua chave de API dá acesso à sua conta inteira. Guarde-a nos seus servidores, em uma variável de ambiente. Nunca a coloque em um navegador, um app móvel ou um repositório público.

### Encontre sua chave de API

Abra o menu do seu avatar, escolha **Configurações do usuário** e depois **Desenvolvedor**, ou vá direto para as [configurações de desenvolvedor](https://dashboard.instatus.com/developer). Clique em **Copiar** ao lado da chave.

![A chave de API nas configurações de desenvolvedor, com um botão para copiá-la](https://instatus.com/help/observability/api-key.png)

### Encontre o ID da sua página

Raramente é necessário: o prompt e o código no painel já o contêm. Para copiá-lo você mesmo, clique com o botão direito no nome do projeto no topo do painel e escolha **Copy Project ID**.

![Copy Project ID no menu do nome do projeto](https://instatus.com/help/observability/copy-page-id.png)

## Envie um log de teste

Uma requisição de um terminal basta para verificar sua chave e o ID da página:

```bash
curl -X POST https://otel.instatus.com/v1/logs \
  -H "Authorization: Bearer $INSTATUS_API_KEY" \
  -H "X-Instatus-Site-Id: $INSTATUS_PAGE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "api" } }
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s)'000000000",
          "severityText": "INFO",
          "body": { "stringValue": "Hello from Instatus" }
        }]
      }]
    }]
  }'
```

Uma resposta `200` significa que o log foi aceito. Abra **Observability** → **Logs** e ele aparece em poucos segundos.

## Qualquer linguagem, sem mudar o código

Todo SDK do OpenTelemetry lê as mesmas variáveis de ambiente. Com elas, a autoinstrumentação envia traces, métricas e logs sem mexer no seu código:

```bash
export OTEL_SERVICE_NAME="api"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.instatus.com"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${INSTATUS_API_KEY},X-Instatus-Site-Id=${INSTATUS_PAGE_ID}"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
```

O espaço depois de `Bearer` é escrito como `%20`, porque a variável de cabeçalhos é codificada como URL. Depois inicie seu app com a autoinstrumentação da linguagem dele:

```bash
# Node.js
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register app.js

# Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py
```

Java, .NET, Go, Ruby e PHP têm autoinstrumentação própria e leem as mesmas variáveis. Veja os [guias zero-code do OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

Para enviar logs a partir do código, instale o SDK de logs:

```bash
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \
  @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
```

Configure-o uma vez ao iniciar o app:

```js
import { SeverityNumber } from '@opentelemetry/api-logs'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs'

const provider = new LoggerProvider({
  resource: resourceFromAttributes({ 'service.name': 'api' }),
  processors: [
    new BatchLogRecordProcessor(
      new OTLPLogExporter({
        url: 'https://otel.instatus.com/v1/logs',
        headers: {
          Authorization: `Bearer ${process.env.INSTATUS_API_KEY}`,
          'X-Instatus-Site-Id': process.env.INSTATUS_PAGE_ID
        }
      })
    )
  ]
})

const logger = provider.getLogger('api')

logger.emit({
  severityNumber: SeverityNumber.ERROR,
  severityText: 'ERROR',
  body: 'Payment failed: card declined',
  attributes: { 'customer.id': 'cus_123', route: '/v2/charges' }
})

process.on('beforeExit', () => provider.shutdown())
```

Já registra logs com **pino** ou **winston**? Mantenha-os. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) e [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) enviam cada linha de log como ela é.

## Python

```bash
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

O SDK se conecta ao módulo `logging` do Python, então suas chamadas de `logging` existentes são enviadas como são:

```python
import logging
import os

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.resources import Resource

provider = LoggerProvider(resource=Resource.create({"service.name": "worker"}))
provider.add_log_record_processor(
    BatchLogRecordProcessor(
        OTLPLogExporter(
            endpoint="https://otel.instatus.com/v1/logs",
            headers={
                "Authorization": f"Bearer {os.environ['INSTATUS_API_KEY']}",
                "X-Instatus-Site-Id": os.environ["INSTATUS_PAGE_ID"],
            },
        )
    )
)
set_logger_provider(provider)

logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=provider))
logging.getLogger().setLevel(logging.INFO)

logging.warning("Card declined for customer %s", "cus_123")
```

## OpenTelemetry Collector

Já roda o OpenTelemetry Collector? Adicione o Instatus como exportador e deixe seus apps como estão:

```yaml
exporters:
  otlphttp/instatus:
    endpoint: https://otel.instatus.com
    headers:
      Authorization: Bearer ${env:INSTATUS_API_KEY}
      X-Instatus-Site-Id: ${env:INSTATUS_PAGE_ID}

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
```

O exportador adiciona `/v1/logs`, `/v1/traces` e `/v1/metrics` sozinho, então o endpoint é só o host. Para enviar arquivos de log, adicione um receptor `filelog` ao pipeline de logs.

## O que enviar

O Instatus lê estes campos. Todo o resto é mantido como atributo, que você pode pesquisar e filtrar.

| Campo                       | Usado para                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (recurso)      | A coluna e o filtro **Serviço**. Defina em cada app, worker e job. |
| `body`                             | A mensagem do log, onde a busca por texto procura.                                                     |
| `severityText` ou `severityNumber` | O nível: `fatal`, `error`, `warn`, `info`, `debug` ou `trace`.                                  |
| `traceId` e `spanId`             | Liga um log ao seu trace, para você ir de um ao outro.                                          |
| Atributos                     | Tudo o que você adicionar, como `customer.id` ou `http.route`. Cada um vira um filtro.               |

Atributos que começam com `instatus.` são reservados e substituídos quando os dados chegam.

## Solução de problemas

| Você vê               | Solução                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Verifique a chave e o cabeçalho `X-Instatus-Site-Id`. O dono da chave precisa ser proprietário, admin ou editor da página.       |
| `400`                       | O corpo não é um OTLP válido. Verifique o `Content-Type` e a estrutura JSON do [log de teste](#envie-um-log-de-teste).             |
| `429`                       | A franquia de dados deste mês acabou. Veja [planos e limites](https://instatus.com/help/pt-br/observability#planos-e-limites).                    |
| `200`, mas nada aparece | Espere alguns segundos e confira o período. Um log com data no passado só aparece se o período a incluir. |
| Absolutamente nada              | Os SDKs enviam em lotes. Garanta que seu app esvazie ou encerre o provider antes de sair.                           |

Gerar uma nova chave de API nas configurações de desenvolvedor desativa a antiga na hora, então atualize antes cada app que a usa.

- [Logs](https://instatus.com/help/pt-br/observability/logs): Pesquise, filtre e acompanhe seus logs ao vivo
- [Traces](https://instatus.com/help/pt-br/observability/traces): Veja onde cada requisição gasta seu tempo
