# 傳送資料

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

Instatus 透過 OpenTelemetry（經由 HTTPS 的 OTLP）接收日誌、追蹤和指標。連接應用程式有兩種方式，擇一即可。

| At a glance | Details |
| :-- | :-- |
| [最快](https://instatus.com/help/zh-tw/observability/send-logs#方式-1複製提示詞) | 為程式設計助理複製提示詞 |
| [手動](https://instatus.com/help/zh-tw/observability/send-logs#方式-2手動設定) | 選擇語言並貼上程式碼 |
| [端點](https://instatus.com/help/zh-tw/observability/send-logs#每個請求需要什麼) | https://otel.instatus.com，再加兩個標頭 |
| [測試](https://instatus.com/help/zh-tw/observability/send-logs#傳送一筆測試日誌) | 一個 curl 請求 |
| [沒有資料？](https://instatus.com/help/zh-tw/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-tw/observability#方案與限制)。                    |
| 回應 `200`，但看不到資料 | 等幾秒，再檢查時間範圍。時間戳記在過去的日誌只有在時間範圍涵蓋時才會顯示。 |
| 完全沒有資料              | SDK 會批次傳送。請確認應用程式在結束前清空或關閉 provider。                           |

在開發者設定中重新產生 API 金鑰後，舊金鑰會立即失效，因此請先更新所有使用它的應用程式。

- [日誌](https://instatus.com/help/zh-tw/observability/logs): 搜尋、篩選並即時查看日誌
- [追蹤](https://instatus.com/help/zh-tw/observability/traces): 查看每個請求把時間花在哪裡
