讓程式設計代理使用這篇文件

開啟 Claude Code、Codex、Cursor 或其他編碼代理的集中提示包，然後將其適應此處介紹的工作流程。

開啟提示詞包連線真實遙測

本頁內容

你將建置什麼
1.從報告SQL開始
2.查詢Telemetry併發布結果
3. 安排報告時間
讓失敗可見
設計一份人們會繼續閱讀的報告

將計劃的 SQL 報告傳送到 Slack

計劃的 SQL 報告將審查的查詢變成了經常性的團隊習慣。有用的版本不僅僅將行貼上到聊天中：它命名時間視窗，包括分母，連結回持久儀表板，並記錄交付是否成功。

本指南使用 Telemetry 查詢 API、Slack 傳入 Webhook 和計劃的 GitHub 操作工作流程。這是一種整合模式，而不是聲稱 Telemetry 具有本機 Slack 報告按鈕。

你將建置什麼

報告工作將：

針對 api_request_completed 執行只讀 SQL 查詢；
將結果格式化為一個小的 Slack Block Kit 訊息；
透過傳入的 webhook 發布它；
因查詢或傳遞錯誤而失敗，因此排程程式會記錄該問題。

您需要 Telemetry API 金鑰、Slack 傳入 Webhook URL、Node.js 20 或更高版本，以及可以設定加密工作流程機密的儲存庫。

Slack 將傳入的 Webhook 記錄為接受 JSON 訊息負載的唯一秘密 URL。使 URL 遠離原始碼控制，如果暴露，則對其進行輪換。參見 Slack 的傳入 webhook 指南。

1.從報告SQL開始

保持第一份報告簡短並以決策為導向：

SELECT
  route,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route
ORDER BY error_rate_pct DESC, requests DESC
LIMIT 5;

該訊息應顯示“過去 24 小時”，而不是“今天”，因為排程程式和讀取器可能使用不同的時區。 requests 列在兩個請求上保持較高的錯誤率，看起來不像是一個大容量事件。

首先測試 Telemetry 中的查詢。確認欄位型別並決定重試是否算作單獨的請求。 API 錯誤率配方包括型別化合約、合成輸出、圖表和操作邊緣情況。

2.查詢Telemetry併發布結果

在將執行報告的儲存庫中將其儲存為 scripts/post-telemetry-report.mjs：

const { TELEMETRY_API_KEY, SLACK_WEBHOOK_URL, TELEMETRY_DASHBOARD_URL } =
  process.env;

if (!TELEMETRY_API_KEY || !SLACK_WEBHOOK_URL) {
  throw new Error(
    "TELEMETRY_API_KEY and SLACK_WEBHOOK_URL are required to run this report"
  );
}

const sql = `
SELECT
  route,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route
ORDER BY error_rate_pct DESC, requests DESC
LIMIT 5
`;

const queryResponse = await fetch("https://api.telemetry.sh/query", {
  method: "POST",
  headers: {
    Authorization: TELEMETRY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: sql, realtime: true, json: true }),
});

if (!queryResponse.ok) {
  throw new Error(
    `Telemetry query failed: ${queryResponse.status} ${await queryResponse.text()}`
  );
}

const queryResult = await queryResponse.json();
const rows = Array.isArray(queryResult.data) ? queryResult.data : [];
const lines =
  rows.length > 0
    ? rows.map(
        (row) =>
          `• \`${row.route}\` — ${row.error_rate_pct}% errors ` +
          `(${row.errors}/${row.requests})`
      )
    : ["• No matching requests in the last 24 hours"];

const dashboardLink = TELEMETRY_DASHBOARD_URL
  ? `\n<${TELEMETRY_DASHBOARD_URL}|Open the Telemetry dashboard>`
  : "";

const slackResponse = await fetch(SLACK_WEBHOOK_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    text: "Daily API reliability report",
    blocks: [
      {
        type: "header",
        text: { type: "plain_text", text: "Daily API reliability" },
      },
      {
        type: "section",
        text: {
          type: "mrkdwn",
          text:
            "*Window:* trailing 24 hours\n" +
            lines.join("\n") +
            dashboardLink,
        },
      },
      {
        type: "context",
        elements: [
          {
            type: "mrkdwn",
            text: "Synthetic example format — validate thresholds and counting rules.",
          },
        ],
      },
    ],
  }),
});

if (!slackResponse.ok) {
  throw new Error(
    `Slack delivery failed: ${slackResponse.status} ${await slackResponse.text()}`
  );
}

console.log(`Posted ${rows.length} report rows to Slack.`);

僅當執行此指令碼時才會發生環境檢查。它們不會向您的應用程式的匯入或啟動路徑新增新的要求。

避免在 Slack 訊息中包含原始錯誤訊息、客戶識別符號、提示或請求負載。將授權讀者連結到儀表板以進行更深入的調查。

3. 安排報告時間

建立.github/workflows/telemetry-report.yml：

name: telemetry reliability report

on:
  schedule:
    - cron: "15 16 * * 1-5"
      timezone: "America/Los_Angeles"
  workflow_dispatch:

jobs:
  post-report:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: node scripts/post-telemetry-report.mjs
        env:
          TELEMETRY_API_KEY: ${{ secrets.TELEMETRY_API_KEY }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
          TELEMETRY_DASHBOARD_URL: ${{ vars.TELEMETRY_DASHBOARD_URL }}

GitHub 計劃的工作流程從預設分支執行。工作流程語法支援 POSIX cron 和 IANA 時區；檢查 GitHub的工作流程語法參考中的當前行為。

新增 TELEMETRY_API_KEY 和 SLACK_WEBHOOK_URL 作為加密的 Actions 金鑰。儀表板 URL 通常不是秘密，因此如果 URL 本身未顯示敏感識別符號，則它可以是儲存庫變數。

推出報告時保留 workflow_dispatch。它允許審閱者在等待第一次計劃執行之前手動執行確切的作業。

讓失敗可見

靜默計劃作業不是作業系統。至少：

讓非 2xx 查詢和 Webhook 回應使工作流程失敗；
保持排程程式的失敗通知處於啟用狀態；
在有界報告事件中記錄 report_name、window_start、window_end、row_count、delivery_status 和 latency_ms；
避免自動重試格式錯誤的有效負載或撤銷的 Webhook；
如果您稍後遷移到支援它的 API，請使用穩定的冪等金鑰。