데이터 보내기

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

방법 1: 프롬프트 복사

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

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

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

방법 2: 직접 설정

  1. 상태 페이지에서 Observability를 여세요.
  2. 직접 설정를 클릭하세요.
  3. 언어를 고르세요: Node.js, Python, Go, Java, .NET, Ruby, PHP 또는 OpenTelemetry Collector.
  4. 설치 명령을 복사해 실행한 뒤, 구성 코드를 앱에 복사하세요.
  5. 환경 변수 INSTATUS_API_KEY를 API 키로 설정하고 앱을 시작하세요.
Node.js를 선택한 직접 설정 화면으로, 설치 명령과 설정 코드가 보임

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

모든 요청에 필요한 것

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

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

API 키 찾기

아바타 메뉴를 열고 사용자 설정, 개발자 순으로 선택하거나 개발자 설정으로 바로 이동하세요. 키 옆의 복사를 클릭하세요.

개발자 설정의 API 키와 복사 버튼

페이지 ID 찾기

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

프로젝트 이름 메뉴의 Copy Project ID

테스트 로그 보내기

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

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는 같은 환경 변수를 읽습니다. 이 변수로 자동 계측이 코드를 건드리지 않고 트레이스, 메트릭, 로그를 보냅니다:

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으로 씁니다. 그런 다음 해당 언어의 자동 계측으로 앱을 시작하세요:

# 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 제로 코드 가이드를 참고하세요.

Node.js

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

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

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

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와 @opentelemetry/winston-transport가 기존 로그 줄을 그대로 보냅니다.

Python

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

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

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를 익스포터로 추가하고 앱은 그대로 두세요:

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이번 달 데이터 한도를 다 썼습니다. 요금제와 한도를 참고하세요.
200인데 아무것도 안 보임몇 초 기다린 뒤 기간을 확인하세요. 과거 타임스탬프의 로그는 기간에 포함될 때만 보입니다.
아무것도 오지 않음SDK는 묶어서 보냅니다. 앱이 종료되기 전에 프로바이더를 플러시하거나 종료하는지 확인하세요.

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