发送数据

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 (资源)服务 列和筛选条件。请在每个应用、worker 和任务中设置。
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 会批量发送。确保应用在退出前刷新或关闭 provider。

在开发者设置中重新生成 API 密钥后,旧密钥会立即失效,因此请先更新所有使用它的应用。