# 发送数据

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

Instatus 通过 OpenTelemetry（基于 HTTPS 的 OTLP）接收日志、链路和指标。连接应用有两种方式，任选其一。

| At a glance | Details |
| :-- | :-- |
| [最快](https://instatus.com/help/zh/observability/send-logs#方式-1复制提示词) | 为编程助手复制一段提示词 |
| [手动](https://instatus.com/help/zh/observability/send-logs#方式-2手动设置) | 选择语言并粘贴代码 |
| [端点](https://instatus.com/help/zh/observability/send-logs#每个请求需要什么) | https://otel.instatus.com，外加两个请求头 |
| [测试](https://instatus.com/help/zh/observability/send-logs#发送一条测试日志) | 一条 curl 请求 |
| [没有数据？](https://instatus.com/help/zh/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` (资源)      | **服务** 列和筛选条件。请在每个应用、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`                       | 本月的数据额度已用完。请参阅[套餐与限制](https://instatus.com/help/zh/observability#套餐与限制)。                    |
| 返回 `200`，但看不到数据 | 等几秒，然后检查时间范围。时间戳在过去的日志只有在时间范围覆盖它时才会显示。 |
| 什么都没有              | SDK 会批量发送。确保应用在退出前刷新或关闭 provider。                           |

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

- [日志](https://instatus.com/help/zh/observability/logs): 搜索、筛选并实时查看日志
- [链路](https://instatus.com/help/zh/observability/traces): 查看每个请求把时间花在哪里
