# Lähetä tiedot

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

Instatus vastaanottaa lokit, jäljet ja metriikat OpenTelemetryllä (OTLP HTTPS:n yli). Sovelluksen voi yhdistää kahdella tavalla. Valitse toinen.

| At a glance | Details |
| :-- | :-- |
| [Nopein](https://instatus.com/help/fi/observability/send-logs#tapa-1-kopioi-kehote) | Kopioi kehote koodausagentillesi |
| [Käsin](https://instatus.com/help/fi/observability/send-logs#tapa-2-määritä-käsin) | Valitse kieli ja liitä koodi |
| [Päätepiste](https://instatus.com/help/fi/observability/send-logs#mitä-jokainen-pyyntö-tarvitsee) | https://otel.instatus.com ja kaksi otsaketta |
| [Testi](https://instatus.com/help/fi/observability/send-logs#lähetä-testiloki) | Yksi curl-pyyntö |
| [Eikö mitään näy?](https://instatus.com/help/fi/observability/send-logs#vianmääritys) | Korjaa yleiset ongelmat |

## Tapa 1: Kopioi kehote

Nopein tapa, jos käytät koodausagenttia, kuten Claude Codea, Cursoria tai Copilotia.

1. Avaa **Observability** tilasivullasi.
2. Valitse kohdassa **Sisällytä**, mitä haluat lähettää: **Lokit**, **Jäljet**, **Metriikat**. Valitse myös **Aloituskoontinäkymä**, jos haluat myöhemmin valmiit koontinäkymät palveluillesi.
3. Napsauta **Kopioi kehote**.
4. Liitä se koodausagenttiisi sovelluksesi projektissa.
5. Aseta [API-avaimesi](#löydä-api-avaimesi) ympäristömuuttujaan `INSTATUS_API_KEY` ja suorita agentin ehdottama testi.

![Asetuskortti, jossa valitaan mukaan lokit, jäljet ja metriikat, sekä painike kehotteen kopioimiseen](https://instatus.com/help/observability/setup.png)

Kehote pyytää agenttia käyttämään kielesi virallista OpenTelemetry-SDK:ta, säilyttämään nykyisen lokikirjastosi, lukemaan avaimen ympäristömuuttujasta eikä koskaan committaamaan sitä. Sivusi tunnus on jo siinä.

## Tapa 2: Määritä käsin

1. Avaa **Observability** tilasivullasi.
2. Napsauta **Määritä käsin**.
3. Valitse kielesi: Node.js, Python, Go, Java, .NET, Ruby, PHP tai OpenTelemetry Collector.
4. Kopioi kohdan **Asenna** komento ja suorita se, kopioi sitten kohdan **Määritä** koodi sovellukseesi.
5. Aseta ympäristömuuttujaan `INSTATUS_API_KEY` [API-avaimesi](#löydä-api-avaimesi) ja käynnistä sovelluksesi.

![Käsin määritys Node.js valittuna, näkyvissä asennuskomento ja asetuskoodi](https://instatus.com/help/observability/setup-by-hand.png)

Koontinäkymän koodissa on sivusi tunnus jo valmiina. Samat esimerkit ovat alla, jos haluat kopioida ne täältä.

## Mitä jokainen pyyntö tarvitsee

| Mitä          | Arvo                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Päätepiste      | `https://otel.instatus.com`. Lokit menevät osoitteeseen `/v1/logs`, jäljet `/v1/traces`, metriikat `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, sivun omistajan, ylläpitäjän tai muokkaajan avaimella.                    |
| `X-Instatus-Site-Id` | Sen tilasivun tunnus, johon data kuuluu.                                                |
| Protokolla      | OTLP HTTP:n yli, protobufina tai JSONina. Jos SDK:si käyttää oletuksena gRPC:tä, vaihda se HTTP:hen.          |

> API-avaimesi antaa pääsyn koko tiliisi. Säilytä se palvelimillasi ympäristömuuttujassa. Älä koskaan laita sitä selaimeen, mobiilisovellukseen tai julkiseen repositorioon.

### Löydä API-avaimesi

Avaa avatar-valikko, valitse **Käyttäjäasetukset** ja sitten **Kehittäjä**, tai siirry suoraan [kehittäjäasetuksiin](https://dashboard.instatus.com/developer). Napsauta avaimen vieressä **Kopioi**.

![API-avain kehittäjäasetuksissa ja kopiointipainike](https://instatus.com/help/observability/api-key.png)

### Löydä sivusi tunnus

Sitä tarvitaan harvoin: kehote ja koontinäkymän koodi sisältävät sen jo. Kopioi se itse napsauttamalla hiiren oikealla painikkeella projektin nimeä koontinäkymän yläreunassa ja valitsemalla **Copy Project ID**.

![Copy Project ID projektin nimen valikossa](https://instatus.com/help/observability/copy-page-id.png)

## Lähetä testiloki

Yksi pyyntö päätteestä riittää avaimen ja sivun tunnuksen tarkistamiseen:

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

Vastaus `200` tarkoittaa, että loki hyväksyttiin. Avaa **Observability** → **Lokit**, niin se näkyy muutamassa sekunnissa.

## Mikä tahansa kieli, ilman koodimuutoksia

Jokainen OpenTelemetry-SDK lukee samat ympäristömuuttujat. Niiden avulla automaattinen instrumentointi lähettää jäljet, metriikat ja lokit koskematta koodiisi:

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

Välilyönti sanan `Bearer` jälkeen kirjoitetaan muodossa `%20`, koska otsakemuuttuja on URL-koodattu. Käynnistä sitten sovellus sen kielen automaattisella instrumentoinnilla:

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

Javalla, .NETillä, Golla, Rubylla ja PHP:llä on oma automaattinen instrumentointinsa, ja ne lukevat samat muuttujat. Katso [OpenTelemetryn zero-code-oppaat](https://opentelemetry.io/docs/zero-code/).

## Node.js

Asenna lokien SDK, jotta voit lähettää lokeja koodistasi:

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

Määritä se kerran sovelluksen käynnistyessä:

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

Lokitatko jo **pinolla** tai **winstonilla**? Pidä ne. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) ja [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) lähettävät jokaisen nykyisen lokirivin sellaisenaan.

## Python

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

SDK kytkeytyy Pythonin `logging`-moduuliin, joten nykyiset `logging`-kutsusi lähetetään sellaisenaan:

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

Käytätkö jo OpenTelemetry Collectoria? Lisää Instatus viejäksi ja jätä sovelluksesi ennalleen:

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

Viejä lisää itse polut `/v1/logs`, `/v1/traces` ja `/v1/metrics`, joten päätepiste on pelkkä isäntä. Lähetä lokitiedostoja lisäämällä lokien putkeen `filelog`-vastaanotin.

## Mitä lähettää

Instatus lukee nämä kentät. Kaikki muu säilytetään määritteenä, jolla voi hakea ja suodattaa.

| Kenttä                       | Käyttö                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (resurssi)      | Sarake ja suodatin **Palvelu**. Aseta se jokaisessa sovelluksessa, workerissa ja työssä. |
| `body`                             | Lokiviesti, josta vapaatekstihaku hakee.                                                     |
| `severityText` tai `severityNumber` | Taso: `fatal`, `error`, `warn`, `info`, `debug` tai `trace`.                                  |
| `traceId` ja `spanId`             | Linkittää lokin sen jälkeen, jotta voit siirtyä niiden välillä.                                          |
| Määritteet                     | Kaikki lisäämäsi, kuten `customer.id` tai `http.route`. Jokaisesta tulee suodatin.               |

Merkkijonolla `instatus.` alkavat määritteet on varattu, ja ne korvataan datan saapuessa.

## Vianmääritys

| Näet               | Korjaus                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Tarkista avain ja otsake `X-Instatus-Site-Id`. Avaimen omistajan on oltava sivun omistaja, ylläpitäjä tai muokkaaja.       |
| `400`                       | Runko ei ole kelvollista OTLP:tä. Tarkista `Content-Type` ja [testilokin](#lähetä-testiloki) JSON-rakenne.             |
| `429`                       | Tämän kuun datakiintiö on käytetty. Katso [paketit ja rajat](https://instatus.com/help/fi/observability#paketit-ja-rajat).                    |
| `200`, mutta mitään ei näy | Odota muutama sekunti ja tarkista sitten aikaväli. Loki, jonka aikaleima on menneisyydessä, näkyy vain, jos aikaväli kattaa sen. |
| Ei yhtään mitään              | SDK:t lähettävät erissä. Varmista, että sovellus tyhjentää tai sulkee providerin ennen lopettamista.                           |

Kun luot uuden API-avaimen kehittäjäasetuksissa, vanha lakkaa toimimasta heti, joten päivitä ensin jokainen sitä käyttävä sovellus.

- [Lokit](https://instatus.com/help/fi/observability/logs): Hae, suodata ja seuraa lokeja suorana
- [Jäljet](https://instatus.com/help/fi/observability/traces): Näe, mihin kukin pyyntö käyttää aikansa
