# 데이터 보내기

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

Instatus는 OpenTelemetry(HTTPS를 통한 OTLP)로 로그, 트레이스, 메트릭을 받습니다. 앱을 연결하는 방법은 두 가지입니다. 하나를 고르세요.

| At a glance | Details |
| :-- | :-- |
| [가장 빠름](https://instatus.com/help/ko/observability/send-logs#방법-1-프롬프트-복사) | 코딩 에이전트용 프롬프트 복사 |
| [직접 설정](https://instatus.com/help/ko/observability/send-logs#방법-2-직접-설정) | 언어를 고르고 코드 붙여 넣기 |
| [엔드포인트](https://instatus.com/help/ko/observability/send-logs#모든-요청에-필요한-것) | https://otel.instatus.com과 헤더 두 개 |
| [테스트](https://instatus.com/help/ko/observability/send-logs#테스트-로그-보내기) | curl 요청 한 번 |
| [아무것도 안 보이나요?](https://instatus.com/help/ko/observability/send-logs#문제-해결) | 흔한 문제 해결 |

## 방법 1: 프롬프트 복사

Claude Code, Cursor, Copilot 같은 코딩 에이전트를 쓴다면 가장 빠른 방법입니다.

1. 상태 페이지에서 **Observability**를 여세요.
2. **포함**에서 보낼 항목을 선택하세요: **로그**, **트레이스**, **메트릭**. 나중에 서비스용 기본 대시보드를 원한다면 **스타터 대시보드**도 선택하세요.
3. **프롬프트 복사**를 클릭하세요.
4. 앱 프로젝트에서 코딩 에이전트에 붙여 넣으세요.
5. [API 키](#api-키-찾기)를 환경 변수 `INSTATUS_API_KEY`에 넣고, 에이전트가 제안하는 테스트를 실행하세요.

![포함할 로그, 트레이스, 메트릭과 프롬프트 복사 버튼이 있는 설정 카드](https://instatus.com/help/observability/setup.png)

프롬프트는 에이전트에게 사용 언어의 공식 OpenTelemetry SDK를 쓰고, 기존 로깅 라이브러리를 유지하고, 키를 환경 변수에서 읽고, 절대 커밋하지 말라고 지시합니다. 페이지 ID는 이미 들어 있습니다.

## 방법 2: 직접 설정

1. 상태 페이지에서 **Observability**를 여세요.
2. **직접 설정**를 클릭하세요.
3. 언어를 고르세요: Node.js, Python, Go, Java, .NET, Ruby, PHP 또는 OpenTelemetry Collector.
4. **설치** 명령을 복사해 실행한 뒤, **구성** 코드를 앱에 복사하세요.
5. 환경 변수 `INSTATUS_API_KEY`를 [API 키](#api-키-찾기)로 설정하고 앱을 시작하세요.

![Node.js를 선택한 직접 설정 화면으로, 설치 명령과 설정 코드가 보임](https://instatus.com/help/observability/setup-by-hand.png)

대시보드의 코드에는 페이지 ID가 이미 채워져 있습니다. 여기서 복사하고 싶다면 같은 예제가 아래에 있습니다.

## 모든 요청에 필요한 것

| 항목          | 값                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| 엔드포인트      | `https://otel.instatus.com`. 로그는 `/v1/logs`, 트레이스는 `/v1/traces`, 메트릭은 `/v1/metrics`로 보냅니다. |
| `Authorization`      | `Bearer <API_KEY>`. 페이지의 소유자, 관리자 또는 편집자의 키를 사용합니다.                    |
| `X-Instatus-Site-Id` | 데이터가 속한 상태 페이지의 ID.                                                |
| 프로토콜      | HTTP를 통한 OTLP(protobuf 또는 JSON). SDK가 기본으로 gRPC를 쓰면 HTTP로 바꾸세요.          |

> API 키는 계정 전체에 접근할 수 있습니다. 서버의 환경 변수에 보관하세요. 브라우저, 모바일 앱, 공개 저장소에는 절대 넣지 마세요.

### API 키 찾기

아바타 메뉴를 열고 **사용자 설정**, **개발자** 순으로 선택하거나 [개발자 설정](https://dashboard.instatus.com/developer)으로 바로 이동하세요. 키 옆의 **복사**를 클릭하세요.

![개발자 설정의 API 키와 복사 버튼](https://instatus.com/help/observability/api-key.png)

### 페이지 ID 찾기

보통은 필요 없습니다. 프롬프트와 대시보드의 코드에 이미 들어 있습니다. 직접 복사하려면 대시보드 상단의 프로젝트 이름을 마우스 오른쪽 버튼으로 클릭하고 **Copy Project ID**를 선택하세요.

![프로젝트 이름 메뉴의 Copy Project ID](https://instatus.com/help/observability/copy-page-id.png)

## 테스트 로그 보내기

키와 페이지 ID를 확인하려면 터미널에서 요청 한 번이면 충분합니다:

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

`200` 응답은 로그가 수락되었다는 뜻입니다. **Observability** → **로그**를 열면 몇 초 안에 나타납니다.

## 모든 언어, 코드 변경 없이

모든 OpenTelemetry SDK는 같은 환경 변수를 읽습니다. 이 변수로 자동 계측이 코드를 건드리지 않고 트레이스, 메트릭, 로그를 보냅니다:

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

헤더 변수는 URL 인코딩되므로 `Bearer` 뒤의 공백은 `%20`으로 씁니다. 그런 다음 해당 언어의 자동 계측으로 앱을 시작하세요:

```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, PHP도 자체 자동 계측이 있고 같은 변수를 읽습니다. [OpenTelemetry 제로 코드 가이드](https://opentelemetry.io/docs/zero-code/)를 참고하세요.

## Node.js

코드에서 로그를 보내려면 로그 SDK를 설치하세요:

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

앱이 시작될 때 한 번 설정하세요:

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

이미 **pino**나 **winston**으로 로그를 남기고 있나요? 그대로 쓰세요. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport)와 [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport)가 기존 로그 줄을 그대로 보냅니다.

## Python

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

SDK가 Python의 `logging` 모듈에 연결되므로 기존 `logging` 호출이 그대로 전송됩니다:

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

이미 OpenTelemetry Collector를 쓰고 있나요? Instatus를 익스포터로 추가하고 앱은 그대로 두세요:

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

익스포터가 `/v1/logs`, `/v1/traces`, `/v1/metrics`를 직접 붙이므로 엔드포인트는 호스트만 적습니다. 로그 파일을 보내려면 로그 파이프라인에 `filelog` 리시버를 추가하세요.

## 보낼 내용

Instatus는 아래 필드를 읽습니다. 나머지는 모두 검색과 필터링에 쓸 수 있는 속성으로 저장됩니다.

| 필드                       | 용도                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (리소스)      | **서비스** 열과 필터. 모든 앱, 워커, 작업에 설정하세요. |
| `body`                             | 로그 메시지. 자유 텍스트 검색의 대상입니다.                                                     |
| `severityText` 또는 `severityNumber` | 레벨: `fatal`, `error`, `warn`, `info`, `debug` 또는 `trace`.                                  |
| `traceId` 및 `spanId`             | 로그를 트레이스와 연결해 서로 오갈 수 있게 합니다.                                          |
| 속성                     | `customer.id`나 `http.route`처럼 추가한 모든 것. 각각 필터가 됩니다.               |

`instatus.`로 시작하는 속성은 예약되어 있으며 데이터가 도착할 때 대체됩니다.

## 문제 해결

| 증상               | 해결                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | 키와 `X-Instatus-Site-Id` 헤더를 확인하세요. 키 소유자는 페이지의 소유자, 관리자 또는 편집자여야 합니다.       |
| `400`                       | 본문이 올바른 OTLP가 아닙니다. `Content-Type`과 [테스트 로그](#테스트-로그-보내기)의 JSON 구조를 확인하세요.             |
| `429`                       | 이번 달 데이터 한도를 다 썼습니다. [요금제와 한도](https://instatus.com/help/ko/observability#요금제와-한도)를 참고하세요.                    |
| `200`인데 아무것도 안 보임 | 몇 초 기다린 뒤 기간을 확인하세요. 과거 타임스탬프의 로그는 기간에 포함될 때만 보입니다. |
| 아무것도 오지 않음              | SDK는 묶어서 보냅니다. 앱이 종료되기 전에 프로바이더를 플러시하거나 종료하는지 확인하세요.                           |

개발자 설정에서 API 키를 다시 생성하면 이전 키는 즉시 작동을 멈춥니다. 먼저 그 키를 쓰는 모든 앱을 업데이트하세요.

- [로그](https://instatus.com/help/ko/observability/logs): 로그를 검색, 필터링하고 실시간으로 확인
- [트레이스](https://instatus.com/help/ko/observability/traces): 각 요청이 어디서 시간을 쓰는지 확인
