將計劃的 SQL 報告傳送到 Slack

團隊需要定期更新時，可以將排程執行的 SQL 報告傳送到 Slack。註明時間範圍和分母，方便理解資料。附上儀表板連結，並記錄傳送是否成功。

本指南使用 Telemetry Query API、Slack 傳入 Webhook 和排程執行的 GitHub Actions 工作流程。執行排程和 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，請使用穩定的冪等金鑰。

Slack 可以針對無效負載、禁用的掛鉤、存檔通道或策略限制返回不同的 4xx 回應。不要盲目地每 4xx 重試一次。將超時或 5xx 視為潛在的暫時性傳送失敗，並透過回退進行上限重試。

設計一份人們會繼續閱讀的報告

把決定放在第一位。有用的報告會列出發生的變化、顯示分母以及證據連結。精心挑選的 10 行通常比貼上到聊天中的 CSV 更好。

當讀者需要任意過濾時，使用表格或儀表板而不是聊天。當回應無法等待計劃的視窗時，請使用警示而不是每日報告。當結果對於訊息而言太大時，請使用出口指南。

可能的後續報告包括按功能劃分的 LLM 成本、後台作業重試結果、Webhook 重試恢復和事件期間對客戶的影響。

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