发送数据
Instatus 通过 OpenTelemetry(基于 HTTPS 的 OTLP)接收日志、链路和指标。连接应用有两种方式,任选其一。
方式 1:复制提示词
如果你使用 Claude Code、Cursor 或 Copilot 等编程助手,这是最快的方式。
- 在你的状态页上打开 Observability。
- 在 包含 下勾选要发送的内容:日志、链路、指标。如果以后想要现成的服务仪表盘,也勾选 入门仪表盘。
- 点击 复制提示词。
- 在应用的项目中,把它粘贴到编程助手里。
- 把你的 API 密钥 放到环境变量
INSTATUS_API_KEY中,然后运行助手建议的测试。

提示词会让助手使用你所用语言的官方 OpenTelemetry SDK,保留现有的日志库,从环境变量读取密钥并且绝不提交它。你的页面 ID 已包含在其中。
方式 2:手动设置
- 在你的状态页上打开 Observability。
- 点击 手动设置。
- 选择你的语言:Node.js、Python、Go、Java、.NET、Ruby、PHP 或 OpenTelemetry Collector。
- 复制 安装 下的命令并运行,然后把 配置 下的代码复制到你的应用中。
- 把环境变量
INSTATUS_API_KEY设置为你的 API 密钥,然后启动应用。

仪表盘中的代码已经填好了你的页面 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 密钥
打开头像菜单,依次选择 用户设置 和 开发者,或直接前往开发者设置。点击密钥旁的 复制。

找到你的页面 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.jsnpm install @opentelemetry/api @opentelemetry/auto-instrumentations-nodenode --require @opentelemetry/auto-instrumentations-node/register app.js# Pythonpip install opentelemetry-distro opentelemetry-exporter-otlpopentelemetry-bootstrap -a installOTEL_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 loggingimport osfrom opentelemetry._logs import set_logger_providerfrom opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporterfrom opentelemetry.sdk._logs import LoggerProvider, LoggingHandlerfrom opentelemetry.sdk._logs.export import BatchLogRecordProcessorfrom opentelemetry.sdk.resources import Resourceprovider = 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.comheaders: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 密钥后,旧密钥会立即失效,因此请先更新所有使用它的应用。