# Invia dati

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

Instatus riceve log, trace e metriche con OpenTelemetry (OTLP su HTTPS). Ci sono due modi per collegare un’app. Scegline uno.

| At a glance | Details |
| :-- | :-- |
| [Il più veloce](https://instatus.com/help/it/observability/send-logs#opzione-1-copia-un-prompt) | Copia un prompt per il tuo agente di programmazione |
| [A mano](https://instatus.com/help/it/observability/send-logs#opzione-2-configura-a-mano) | Scegli il linguaggio e incolla il codice |
| [Endpoint](https://instatus.com/help/it/observability/send-logs#cosa-serve-a-ogni-richiesta) | https://otel.instatus.com, più due header |
| [Prova](https://instatus.com/help/it/observability/send-logs#invia-un-log-di-prova) | Una richiesta curl |
| [Non compare nulla?](https://instatus.com/help/it/observability/send-logs#risoluzione-dei-problemi) | Risolvi i problemi più comuni |

## Opzione 1: Copia un prompt

Il modo più rapido, se usi un agente di programmazione come Claude Code, Cursor o Copilot.

1. Apri **Observability** sulla tua pagina di stato.
2. In **Includi**, spunta cosa vuoi inviare: **Log**, **Trace**, **Metriche**. Spunta anche **Dashboard iniziale** se in seguito vuoi dashboard pronte per i tuoi servizi.
3. Fai clic su **Copia prompt**.
4. Incollalo nel tuo agente di programmazione, nel progetto della tua app.
5. Metti la tua [chiave API](#trova-la-tua-chiave-api) nella variabile d’ambiente `INSTATUS_API_KEY`, poi esegui la prova suggerita dall’agente.

![La scheda di configurazione, con log, trace e metriche da includere e un pulsante per copiare il prompt](https://instatus.com/help/observability/setup.png)

Il prompt dice all’agente di usare l’SDK ufficiale di OpenTelemetry per il tuo linguaggio, mantenere la tua libreria di log attuale, leggere la chiave da una variabile d’ambiente e non fare mai il commit. L’ID della tua pagina è già incluso.

## Opzione 2: Configura a mano

1. Apri **Observability** sulla tua pagina di stato.
2. Fai clic su **Configura a mano**.
3. Scegli il tuo linguaggio: Node.js, Python, Go, Java, .NET, Ruby, PHP o l’OpenTelemetry Collector.
4. Copia il comando **Installa** ed eseguilo, poi copia il codice **Configura** nella tua app.
5. Imposta la variabile d’ambiente `INSTATUS_API_KEY` con la tua [chiave API](#trova-la-tua-chiave-api) e avvia la tua app.

![Configurazione a mano con Node.js selezionato, con il comando di installazione e il codice di configurazione](https://instatus.com/help/observability/setup-by-hand.png)

Il codice nella dashboard contiene già l’ID della tua pagina. Trovi gli stessi esempi qui sotto, se preferisci copiarli da qui.

## Cosa serve a ogni richiesta

| Cosa          | Valore                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Endpoint      | `https://otel.instatus.com`. I log vanno a `/v1/logs`, le trace a `/v1/traces`, le metriche a `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, con la chiave di un proprietario, amministratore o editor della pagina.                    |
| `X-Instatus-Site-Id` | L’ID della pagina di stato a cui appartengono i dati.                                                |
| Protocollo      | OTLP su HTTP, in protobuf o JSON. Se il tuo SDK usa gRPC per impostazione predefinita, passalo a HTTP.          |

> La tua chiave API dà accesso a tutto il tuo account. Tienila sui tuoi server, in una variabile d’ambiente. Non metterla mai in un browser, in un’app mobile o in un repository pubblico.

### Trova la tua chiave API

Apri il menu del tuo avatar, scegli **Impostazioni utente**, poi **Sviluppatori**, oppure vai direttamente alle [impostazioni sviluppatore](https://dashboard.instatus.com/developer). Fai clic su **Copia** accanto alla chiave.

![La chiave API nelle impostazioni sviluppatore, con un pulsante per copiarla](https://instatus.com/help/observability/api-key.png)

### Trova l’ID della tua pagina

Serve di rado: il prompt e il codice nella dashboard lo contengono già. Per copiarlo da solo, fai clic destro sul nome del progetto in alto nella dashboard e scegli **Copy Project ID**.

![Copy Project ID nel menu del nome del progetto](https://instatus.com/help/observability/copy-page-id.png)

## Invia un log di prova

Basta una richiesta da terminale per verificare la chiave e l’ID della pagina:

```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" }
        }]
      }]
    }]
  }'
```

Una risposta `200` significa che il log è stato accettato. Apri **Observability** → **Log** e lo trovi lì in pochi secondi.

## Qualsiasi linguaggio, senza modificare il codice

Ogni SDK di OpenTelemetry legge le stesse variabili d’ambiente. Con queste, l’auto-strumentazione invia trace, metriche e log senza toccare il tuo codice:

```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"
```

Lo spazio dopo `Bearer` si scrive `%20`, perché la variabile degli header è codificata come URL. Poi avvia la tua app con l’auto-strumentazione del suo linguaggio:

```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 hanno la propria auto-strumentazione e leggono le stesse variabili. Vedi le [guide zero-code di OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

Per inviare log dal tuo codice, installa l’SDK dei log:

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

Configuralo una volta all’avvio della tua 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())
```

Usi già **pino** o **winston**? Tienili. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) e [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) inviano ogni riga di log così com’è.

## Python

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

L’SDK si collega al modulo `logging` di Python, quindi le tue chiamate `logging` esistenti vengono inviate così come sono:

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

Usi già l’OpenTelemetry Collector? Aggiungi Instatus come exporter e lascia le tue app come sono:

```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]
```

L’exporter aggiunge da solo `/v1/logs`, `/v1/traces` e `/v1/metrics`, quindi l’endpoint è solo l’host. Per inviare file di log, aggiungi un receiver `filelog` alla pipeline dei log.

## Cosa inviare

Instatus legge questi campi. Tutto il resto viene conservato come attributo, su cui puoi cercare e filtrare.

| Campo                       | Serve per                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (risorsa)      | La colonna e il filtro **Servizio**. Impostalo in ogni app, worker e job. |
| `body`                             | Il messaggio del log, su cui lavora la ricerca a testo libero.                                                     |
| `severityText` o `severityNumber` | Il livello: `fatal`, `error`, `warn`, `info`, `debug` o `trace`.                                  |
| `traceId` e `spanId`             | Collega un log alla sua trace, per passare dall’uno all’altra.                                          |
| Attributi                     | Qualsiasi cosa aggiungi, come `customer.id` o `http.route`. Ognuno diventa un filtro.               |

Gli attributi che iniziano con `instatus.` sono riservati e vengono sostituiti all’arrivo dei dati.

## Risoluzione dei problemi

| Vedi               | Soluzione                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Controlla la chiave e l’header `X-Instatus-Site-Id`. Il titolare della chiave deve essere proprietario, amministratore o editor della pagina.       |
| `400`                       | Il body non è OTLP valido. Controlla `Content-Type` e la struttura JSON nel [log di prova](#invia-un-log-di-prova).             |
| `429`                       | Il volume di dati di questo mese è esaurito. Vedi [piani e limiti](https://instatus.com/help/it/observability#piani-e-limiti).                    |
| `200`, ma non compare nulla | Attendi qualche secondo, poi controlla l’intervallo di tempo. Un log con un timestamp nel passato compare solo se l’intervallo lo copre. |
| Proprio niente              | Gli SDK inviano a lotti. Assicurati che la tua app svuoti o chiuda il provider prima di terminare.                           |

Rigenerare la chiave API nelle impostazioni sviluppatore disattiva subito quella vecchia, quindi aggiorna prima ogni app che la usa.

- [Log](https://instatus.com/help/it/observability/logs): Cerca, filtra e segui in diretta i tuoi log
- [Trace](https://instatus.com/help/it/observability/traces): Scopri dove ogni richiesta passa il suo tempo
