MENU

問い合わせ

    お問い合わせ


    【Honoで作る社内ヘルプデスク 第10回】ログとエラー処理・監視:Workers Logsと問い合わせ番号で「何が起きたか」を追えるようにする

    社内ヘルプデスクは、登録・一覧・コメント・通知・期限超過の検知・管理画面・型つきの呼び出しまでそろいました。本番に出す前に決めておきたいのが、動かしたあとに「何が起きたか」を後から追える仕組み、つまりログとエラー処理・監視です。

    「社員から『ヘルプデスクでエラーが出た』と連絡が来ても、いつ・どの画面で・何が起きたのか分からない。原因を調べられるようにしておくには、何を作っておけばいいの?」

    結論から言うと、リクエストごとに「問い合わせ番号(リクエストID)」を付けて応答とログの両方に載せ、ログを項目つきのオブジェクトで残し、エラーの応答の形を1か所で決めることで、利用者の連絡からログの1行までたどれるようになります。Cloudflare Workers では、ログの保存先(Workers Logs)とエラーのまとめ機能(Issues)を設定ファイルで有効にできます。

    前回は、hono/client で API を型つきで呼べるようにしました。まだの方は先にご覧ください。

    詳しくは前回の記事で解説しています。

    新しいライブラリのインストールは不要です。この回で使う request-id・route・http-exception・html は、どれも hono に含まれています。

    目次

    ログとエラー処理で、この回に決めること

    この回で作るものと、それぞれの役目を先に整理します。

    作るもの役目置き場所
    問い合わせ番号(リクエストID)1件のリクエストに番号を付け、応答ヘッダー X-Request-Id とログの両方に載せるsrc/observability.ts
    アクセスログ1件のリクエストごとに「どのルート・状態コード・かかった時間・利用者の番号」を1行残すsrc/observability.ts
    エラー応答の統一想定外の例外は 500 と番号だけを返し、原因はログにだけ残す。API は JSON、管理画面は HTML で返すsrc/observability.ts
    ログの書き方の統一level(重さ)と event(何が起きたか)を必ず付けたオブジェクトで出すsrc/log.ts
    監視の入口D1 に届かないときヘルスチェックが 503 を返す。Workers Logs と Issues を有効にするsrc/index.ts・wrangler.jsonc

    ログを「オブジェクト」で出すのは、Workers Logs がその項目を索引にし、request_id や level で絞り込めるようにするためです。文字列に埋め込むと全文検索でしか探せません。

    📰 出典:Cloudflare Docs「Workers Logs」

    1. ログの書き方を1か所にまとめる

    まず、ログを出す関数を1つ作り、どこからでも同じ形(level・event・項目)で出せるようにします。ログは画面より多くの人が見るため、個人情報は番号(利用者 ID・チケット番号)で残し、必要なときに DB から引きます。

    新しく src/log.ts を作ります。

    // src/log.ts
    // ログは「1件 = 1つのオブジェクト」で出す。Workers Logs はオブジェクトの項目を取り出して索引を作るので、
    // 管理画面で「level が error」「request_id が …」のように項目で絞り込める(文字列に埋め込むと全文検索しかできない)
    type Level = 'info' | 'warn' | 'error'
    type Value = string | number | boolean | null | undefined
    export type LogFields = Record<string, Value>
    
    // event は「何が起きたか」を表す短い英語の名前(request / unhandled_error など)。集計や絞り込みの軸にする。
    // メールアドレス・氏名・問い合わせの本文は載せない(ログは画面より多くの人が見る。必要なら利用者の番号で引く)
    export const log = (level: Level, event: string, fields: LogFields = {}) => {
      const entry = { level, event, ...fields }
      if (level === 'error') console.error(entry)
      else if (level === 'warn') console.warn(entry)
      else console.log(entry)
    }
    
    // 例外をログの項目にする。stack(どこで起きたか)はログにだけ残し、利用者への応答には入れない
    export const errorFields = (e: unknown): LogFields =>
      e instanceof Error
        ? { error_name: e.name, error_message: e.message, stack: e.stack }
        : { error_message: String(e) }

    level は console.error・console.warn・console.log の使い分けにつながります。後で出てくる Issues は console.error を「エラー」として数えるため、利用者の操作で普通に起きること(ログイン切れの 401 など)は warn、こちらの不具合は error と分けておくと、エラーの一覧が本当の不具合だけになります。

    2. 問い合わせ番号・アクセスログ・エラー応答を作る

    次に、この回の中心になる src/observability.ts を作ります。中身は4つです。

    • withRequestId:Hono の request-id ミドルウェアで番号を付けます。Cloudflare が付ける cf-ray ヘッダーがあれば、それを番号にして Cloudflare 側の記録と突き合わせられるようにします。記号や改行の混じった X-Request-Id を使わない動きは、ミドルウェアに最初から入っています
    • accessLog:await next() のあとで状態コードを見て、1行のログにします。route には /api/tickets/:id{[0-9]+} のような登録したときの形を入れます(helper の routePath)。実際の URL(/api/tickets/123)だと番号ごとにばらけて、「どの API が遅いか」を集計しにくいためです
    • handleNotFound:どのルートにも当たらなかったときの応答です
    • handleError:ルートやミドルウェアで投げられた例外が、すべてここに集まります(app.onError)

    handleError では、例外を2種類に分けます。HTTPException は、Hono の部品が「このリクエストは受け付けない」と分かって投げたもので、たとえば JSON の形が壊れているときの 400 や、ほかのサイトからのフォーム送信を止めた 403(第8回の hono/csrf)です。これは想定内なので warn にし、状態コードはそのまま返します。それ以外の例外は想定外の不具合として error にし、利用者には internal_error と番号だけを返します。

    📰 出典:Hono「HTTPException」

    新しく src/observability.ts を作ります。

    <details> <summary>src/observability.ts の全文</summary>

    // src/observability.ts
    // 第10回: 問い合わせ番号(リクエストID)・アクセスログ・エラー応答の統一
    import type { Context, ErrorHandler, NotFoundHandler } from 'hono'
    import { html } from 'hono/html'
    import { createMiddleware } from 'hono/factory'
    import { HTTPException } from 'hono/http-exception'
    import { requestId } from 'hono/request-id'
    import { routePath } from 'hono/route'
    import type { ContentfulStatusCode } from 'hono/utils/http-status'
    import type { AppEnv } from './auth'
    import { errorFields, log } from './log'
    
    // 1件のリクエストに番号を付け、応答ヘッダー X-Request-Id でも返す。
    // Cloudflare 上では、Cloudflare が付ける番号(cf-ray ヘッダー)をそのまま使い、Cloudflare 側の記録とも突き合わせられるようにする
    export const withRequestId = requestId({
      limitLength: 64,
      generator: (c) => c.req.header('cf-ray') ?? crypto.randomUUID(),
    })
    
    // 1件のリクエストごとに、結果を1行のログにする。
    // route は「/api/tickets/:id」のような登録したときの形(番号ごとにばらけないので集計しやすい)。
    // next() のあとの routePath(c) は、最後に応答を返したルートの形を指す
    export const accessLog = createMiddleware<AppEnv>(async (c, next) => {
      const started = Date.now()
      await next()
      const status = c.res.status
      // 401・404 などは利用者の操作で普通に起きるので warn、500 台はこちらの不具合なので error
      log(status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info', 'request', {
        request_id: c.get('requestId'),
        method: c.req.method,
        route: routePath(c) || null,
        status,
        duration_ms: Date.now() - started,
        // ログイン済みなら利用者の番号だけを残す(メールアドレスは残さない)
        user_id: c.get('user')?.id ?? null,
      })
    })
    
    // 状態コードごとの、API が返すエラーの名前。画面やスクリプトはこの名前で分岐する
    const errorCode = (status: number) =>
      ({ 400: 'invalid_request', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 413: 'too_large' })[status] ??
      'error'
    
    // 管理画面(HTML)へのリクエストには HTML で、API には JSON で返す
    const isPage = (c: Context) => c.req.path.startsWith('/admin')
    
    const errorPage = (c: Context<AppEnv>, status: ContentfulStatusCode, message: string) =>
      c.html(
        html`<!doctype html>
          <html lang="ja">
            <head><meta charset="utf-8" /><title>エラー|社内ヘルプデスク</title></head>
            <body>
              <h1>${message}</h1>
              <p>問い合わせ番号:${c.get('requestId')}</p>
              <p><a href="/admin">管理画面のトップへ戻る</a></p>
            </body>
          </html>`,
        status,
      )
    
    // どのルートにも当たらなかったとき
    export const handleNotFound: NotFoundHandler<AppEnv> = (c) => {
      if (isPage(c)) return errorPage(c, 404, 'ページが見つかりません')
      return c.json({ error: 'not_found', requestId: c.get('requestId') }, 404)
    }
    
    // ルートやミドルウェアで投げられた例外は、すべてここに集まる
    export const handleError: ErrorHandler<AppEnv> = (err, c) => {
      const requestId = c.get('requestId')
    
      // HTTPException は、Hono の部品が「このリクエストは受け付けない」と分かって投げたもの
      // (JSON の形が壊れている 400、ほかのサイトからのフォーム送信の 403 など)。想定内なので warn にする
      if (err instanceof HTTPException) {
        log('warn', 'http_exception', { request_id: requestId, status: err.status, message: err.message })
        if (isPage(c)) return errorPage(c, err.status, 'この操作は受け付けられませんでした')
        // err.getResponse() を返すと、c に付けたヘッダー(X-Request-Id など)が落ちるので、c.json で作り直す
        return c.json({ error: errorCode(err.status), requestId }, err.status)
      }
    
      // それ以外は想定外の不具合。原因はログにだけ残し、利用者には中身を見せない
      log('error', 'unhandled_error', {
        request_id: requestId,
        method: c.req.method,
        route: routePath(c) || null,
        ...errorFields(err),
      })
      if (isPage(c)) return errorPage(c, 500, 'エラーが起きました。時間をおいてもう一度お試しください')
      return c.json({ error: 'internal_error', requestId }, 500)
    }

    </details>

    なお、公式の例にある err.getResponse() では、ミドルウェアが付けたヘッダー(X-Request-Id)が応答から落ちます(公式ドキュメントにも注意書きがあります)。そのため c.json で応答を作り直しています。

    3. アプリ全体に組み込む

    作った部品を src/index.ts に組み込みます。app.use('*', …) は、どのルートよりも先に登録します。後から登録すると、先に応答を返したルートには番号もログも付きません。

    あわせて、ヘルスチェック(/api/health)を、D1 に届かないときは 503 を返す形に直します。外の監視サービスからこの URL を定期的に呼べば、DB の不調まで見張れます。

    定期実行(scheduled)は、失敗をログに残してから例外を投げ直します。握りつぶすと、その回が「成功」に見えるためです。

    src/index.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/index.ts
    +++ b/src/index.ts
    @@ -8,17 +8,31 @@ import { comments } from './routes/comments'
     import { admin } from './routes/admin'
     import { processBatch, type NotificationMessage } from './notify'
     import { detectOverdue } from './sla'
    +import { errorFields, log } from './log'
    +import { accessLog, handleError, handleNotFound, withRequestId } from './observability'
    
     const app = new Hono<AppEnv>()
    
    +// 第10回: すべてのリクエストに番号を付け、結果をログに残す。どのルートより先に登録する
    +app.use('*', withRequestId, accessLog)
    +// 例外と「ルートが無い」は、ここで決めた形の応答にそろえる
    +app.onError(handleError)
    +app.notFound(handleNotFound)
    +
     app.get('/', (c) => c.text(`${c.env.APP_NAME} は動いています`))
    
     // D1 にも届くかまで確認するヘルスチェック(監視・デプロイ後の確認に使う)
    +// 第10回: D1 に届かないときは 503 を返す。外の監視サービスは「200 以外」で異常と判断できる
     app.get('/api/health', async (c) => {
    -  const row = await c.env.DB.prepare('SELECT value FROM app_meta WHERE key = ?')
    -    .bind('schema_version')
    -    .first<{ value: string }>()
    -  return c.json({ status: 'ok', schemaVersion: row?.value ?? null })
    +  try {
    +    const row = await c.env.DB.prepare('SELECT value FROM app_meta WHERE key = ?')
    +      .bind('schema_version')
    +      .first<{ value: string }>()
    +    return c.json({ status: 'ok', schemaVersion: row?.value ?? null })
    +  } catch (e) {
    +    log('error', 'health_check_failed', { request_id: c.get('requestId'), ...errorFields(e) })
    +    return c.json({ status: 'error' }, 503)
    +  }
     })
    
     // 第9回: hono/client から呼ぶルートは、つなげて登録し、その結果の型を AppType として書き出す
    @@ -37,7 +51,13 @@ export default {
       fetch: app.fetch,
       queue: (batch: MessageBatch<NotificationMessage>, env: Env) => processBatch(batch, env),
       // scheduledTime は「本来動くはずだった時刻」。遅れて動いても、この時刻を基準に判定する
    +  // 第10回: 失敗したらログに残してから投げ直す(投げ直すと、Cloudflare の記録でもこの回が「失敗」になる)
       scheduled: async (controller: ScheduledController, env: Env) => {
    -    await detectOverdue(env, new Date(controller.scheduledTime))
    +    try {
    +      await detectOverdue(env, new Date(controller.scheduledTime))
    +    } catch (e) {
    +      log('error', 'scheduled_failed', { cron: controller.cron, ...errorFields(e) })
    +      throw e
    +    }
       },
     } satisfies ExportedHandler<Env, NotificationMessage>

    requestId を、どのルートからでも型つきで読めるように、AppEnv に足します。src/auth.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/auth.ts
    +++ b/src/auth.ts
    @@ -2,12 +2,14 @@ import type { Context } from 'hono'
     import { createMiddleware } from 'hono/factory'
     import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
     import { sign, verify } from 'hono/jwt'
    +import type { RequestIdVariables } from 'hono/request-id'
    
     export const roles = ['employee', 'agent', 'admin'] as const
     export type Role = (typeof roles)[number]
    
     export type SessionUser = { id: number; email: string; name: string; role: Role }
    -export type AppEnv = { Bindings: Env; Variables: { user: SessionUser } }
    +// 第10回: requestId(問い合わせ番号)も、どのルートからでも c.get('requestId') で読めるようにする
    +export type AppEnv = { Bindings: Env; Variables: { user: SessionUser } & RequestIdVariables }
    
     const COOKIE = 'session'
     const SESSION_SECONDS = 8 * 60 * 60

    4. キューと定期実行のログも同じ形にそろえる

    第5回・第7回で console.error や console.log に文字列で書いていたログも、log() に置き換えます。キューの再試行は、まだ再試行が残っているあいだは warn、上限を超えて dead letter queue(送れなかったメッセージの置き場)へ移る最後の失敗だけ error にしました。一時的なメール送信の失敗まで error にすると、エラーの一覧が埋まって本当に見るべきものが埋もれます。

    また、メール送信の失敗のログには宛先のメールアドレスを載せず、チケット番号と通知の種類だけを残します。

    src/notify.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/notify.ts
    +++ b/src/notify.ts
    @@ -2,6 +2,7 @@
     import { sendMail, type SendMail } from './mail'
     import { assignedRecipients, commentRecipients, overdueRecipients, type Staff } from './recipients'
     import { dueAt, type Priority } from './sla'
    +import { errorFields, log } from './log'
    
     // キューに入れるメッセージ。チケットの中身は入れず、番号だけにする
     // (本文や個人情報をキューに残さない。送る直前に D1 から最新を読む)
    @@ -16,7 +17,7 @@ export const enqueueNotification = async (env: Env, message: NotificationMessage
       try {
         await env.NOTIFY_QUEUE.send(message)
       } catch (e) {
    -    console.error('通知をキューに入れられませんでした', message, e)
    +    log('error', 'enqueue_failed', { kind: message.kind, ticket_id: message.ticketId, ...errorFields(e) })
       }
     }
    
    @@ -137,20 +138,33 @@ export const handleMessage = async (env: Env, message: NotificationMessage, send
             .run()
         } catch (e) {
           failed++
    -      console.error('通知メールを送れませんでした', { ticketId: ticket.id, kind: notice.logKind }, e)
    +      // 宛先のメールアドレスはログに残さない(どの通知が失敗したかは、チケット番号と種類で分かる)
    +      log('error', 'mail_send_failed', { ticket_id: ticket.id, kind: notice.logKind, ...errorFields(e) })
         }
       }
       if (failed > 0) throw new Error(`${failed} 件の宛先に送れませんでした`)
     }
    
    +// wrangler.jsonc の max_retries と同じ値にする
    +export const MAX_RETRIES = 3
    +
     // キューから届いたメッセージの束を処理する。成功は ack(処理済みの合図)、失敗は retry(待ってから再配信)
     export const processBatch = async (batch: MessageBatch<NotificationMessage>, env: Env, send: SendMail = sendMail) => {
       for (const msg of batch.messages) {
         try {
           await handleMessage(env, msg.body, send)
           msg.ack()
    -    } catch {
    -      // 上限(wrangler.jsonc の max_retries)を超えると、Cloudflare が dead_letter_queue へ移す
    +    } catch (e) {
    +      // 上限(MAX_RETRIES)を超えると、Cloudflare が dead_letter_queue へ移す。
    +      // 第10回: 最後の失敗は「人が見るべきもの」なので error、まだ再試行が残っているあいだは warn にする
    +      const givingUp = msg.attempts > MAX_RETRIES
    +      log(givingUp ? 'error' : 'warn', givingUp ? 'notification_dead_lettered' : 'notification_retry', {
    +        message_id: msg.id,
    +        kind: msg.body.kind,
    +        ticket_id: msg.body.ticketId,
    +        attempts: msg.attempts,
    +        ...errorFields(e),
    +      })
           msg.retry({ delaySeconds: retryDelaySeconds(msg.attempts) })
         }
       }

    src/sla.ts に次の変更を加えます(+ が追加、- が削除)。

    --- a/src/sla.ts
    +++ b/src/sla.ts
    @@ -1,6 +1,7 @@
     // src/sla.ts
     // 期限超過の検知。Cron Triggers(定期実行)から呼ぶ
     import type { NotificationMessage } from './notify'
    +import { log } from './log'
    
     // 優先度ごとの「解決までの目安の時間」。営業時間ではなく、登録からの経過時間で数える
     export const SLA_HOURS = { high: 4, normal: 24, low: 72 } as const
    @@ -58,6 +59,6 @@ export const detectOverdue = async (env: Env, now: Date, queue: Sender = env.NOT
           ),
         ),
       )
    -  console.log(`期限超過を ${rows.length} 件見つけ、通知をキューに預けました`)
    +  log('info', 'overdue_detected', { count: rows.length })
       return rows.length
     }

    5. Workers Logs と Issues を有効にする

    最後に、wrangler.jsonc の observability を書き足します。enabled でログを Workers Logs に残し、head_sampling_rate(残す割合。1 ですべて)を明示します。issues は、例外・500 台の応答・console.error で出したログを、同じ原因ごとにまとめて一覧にする機能で、Wrangler 4.134.0 以降で設定できます。

    wrangler.jsonc に次の変更を加えます(+ が追加、- が削除)。

    --- a/wrangler.jsonc
    +++ b/wrangler.jsonc
    @@ -3,7 +3,13 @@
       "name": "hono-helpdesk",
       "main": "src/index.ts",
       "compatibility_date": "2026-08-01",
    -  "observability": { "enabled": true },
    +  // 第10回: ログを Workers Logs に残す。head_sampling_rate は残す割合(1 = すべて)。
    +  // issues は、例外・500 台の応答・console.error を、同じ原因ごとにまとめて一覧にする機能(2026年11月時点で open beta)
    +  "observability": {
    +    "enabled": true,
    +    "head_sampling_rate": 1,
    +    "issues": { "enabled": true }
    +  },
       "vars": {
         "APP_NAME": "社内ヘルプデスク",
         "MAIL_FROM": "helpdesk@example.com",

    執筆時点(2026年11月)の公式ドキュメントでの条件は、次のとおりです。

    項目Free プランWorkers Paid プラン
    Workers Logs の量1日 200,000 件まで月 2,000 万件まで含まれ、超えた分は 100 万件あたり 0.60 米ドル
    Workers Logs の保存期間3日7日
    Issuesopen beta の期間中は無料open beta の期間中は無料

    公式ドキュメントには、2026年12月1日から Workers Logs の料金が Cloudflare Observability の料金に移ると書かれています。本番で使う前に、最新の料金ページを確かめてください。head_sampling_rate を 0.1(10件に1件)に下げるとログは減りますが、問い合わせ番号で探しても見つからないことが起きます。社内ツールの規模なら、まずはすべて残す設定で足りることが多いです。

    📰 出典:Cloudflare Docs「Workers Logs」

    📰 出典:Cloudflare Docs「Issues」

    6. テストで確かめる

    テストでは、次の4つを確かめます。

    • すべての応答に X-Request-Id が付き、cf-ray があればそれを使い、記号の混じった番号は使わない
    • 存在しない API は JSON の 404、管理画面は HTML の 404 で、どちらも番号を返す。JSON の形が壊れた登録は、ほかの入力エラーと同じ invalid_request の 400 になる
    • 想定外の例外は 500 で、応答に原因(例外のメッセージ)が出ず、ログには同じ番号・ルート・stack が残る
    • アクセスログにメールアドレスが入らない。D1 に届かないときヘルスチェックが 503 になる。キューの最後の失敗だけ error になる

    想定外の例外は、本物と同じ部品(withRequestId・accessLog・handleError)を付けた小さなアプリで起こして確かめます。D1 に届かない状態は、必ず例外を投げる偽物の DB で作ります。

    新しく test/observability.test.ts を作ります。

    <details> <summary>test/observability.test.ts の全文</summary>

    import { env, SELF } from 'cloudflare:test'
    import { Hono } from 'hono'
    import { afterEach, describe, expect, it, vi } from 'vitest'
    import type { AppEnv } from '../src/auth'
    import { app } from '../src/index'
    import { processBatch, type NotificationMessage } from '../src/notify'
    import { accessLog, handleError, handleNotFound, withRequestId } from '../src/observability'
    import { loginAs } from './helpers'
    
    // console.log / warn / error に渡されたオブジェクトのうち、event が一致するものを探す
    const logged = (spy: { mock: { calls: unknown[][] } }, event: string) =>
      spy.mock.calls.map((args) => args[0] as Record<string, unknown>).filter((entry) => entry?.event === event)
    
    afterEach(() => vi.restoreAllMocks())
    
    describe('問い合わせ番号(X-Request-Id)', () => {
      it('すべての応答に番号が付く', async () => {
        const res = await SELF.fetch('http://example.com/api/health')
        expect(res.headers.get('x-request-id')).toMatch(/^[\w-]+$/)
      })
    
      it('Cloudflare の cf-ray があれば、それを番号にする', async () => {
        const res = await SELF.fetch('http://example.com/api/health', { headers: { 'cf-ray': '8f00aa11bb22cc33-NRT' } })
        expect(res.headers.get('x-request-id')).toBe('8f00aa11bb22cc33-NRT')
      })
    
      it('送られてきた番号に記号や改行が混じっていたら使わず、新しく作る', async () => {
        const res = await SELF.fetch('http://example.com/api/health', { headers: { 'x-request-id': 'abc def<script>' } })
        expect(res.headers.get('x-request-id')).not.toContain('<')
      })
    })
    
    describe('エラー応答の形をそろえる', () => {
      it('存在しない API は JSON の 404 で、番号も返す', async () => {
        // /api の下はログインが必要なルートがまとめて受けるので、ログインした状態で確かめる
        const cookie = await loginAs('obs-agent@example.com', 'agent')
        const res = await SELF.fetch('http://example.com/api/no-such-route', { headers: { cookie } })
        expect(res.status).toBe(404)
        const body = await res.json<{ error: string; requestId: string }>()
        expect(body.error).toBe('not_found')
        expect(body.requestId).toBe(res.headers.get('x-request-id'))
      })
    
      it('管理画面の存在しないページは HTML の 404 で、番号を画面に出す', async () => {
        const res = await SELF.fetch('http://example.com/admin/no-such-page/x')
        expect(res.status).toBe(404)
        expect(res.headers.get('content-type')).toContain('text/html')
        expect(await res.text()).toContain(`問い合わせ番号:${res.headers.get('x-request-id')}`)
      })
    
      it('JSON の形が壊れた登録は、ほかの入力エラーと同じ invalid_request の 400', async () => {
        vi.spyOn(console, 'warn').mockImplementation(() => {})
        const cookie = await loginAs('obs-employee@example.com', 'employee')
        const res = await SELF.fetch('http://example.com/api/tickets', {
          method: 'POST',
          headers: { 'content-type': 'application/json', cookie },
          body: '{"title": "閉じかっこが無い"',
        })
        expect(res.status).toBe(400)
        expect(await res.json()).toMatchObject({ error: 'invalid_request' })
      })
    
      it('想定外の例外は 500。原因はログにだけ残し、応答には出さない', async () => {
        const error = vi.spyOn(console, 'error').mockImplementation(() => {})
        // 本物のアプリと同じ部品をつけた小さなアプリで、わざと例外を起こす
        const test = new Hono<AppEnv>()
          .use('*', withRequestId, accessLog)
          .get('/api/boom', () => {
            throw new Error('D1 の列名を間違えた(利用者に見せてはいけない内容)')
          })
        test.onError(handleError)
        test.notFound(handleNotFound)
    
        const res = await test.request('/api/boom', {}, env)
        expect(res.status).toBe(500)
        const text = await res.text()
        expect(text).not.toContain('列名')
        const body = JSON.parse(text) as { error: string; requestId: string }
        expect(body.error).toBe('internal_error')
    
        // ログには、同じ番号・どのルートか・原因(stack つき)が残る
        const [entry] = logged(error, 'unhandled_error')
        expect(entry).toMatchObject({ level: 'error', request_id: body.requestId, route: '/api/boom' })
        expect(String(entry!.error_message)).toContain('列名')
        expect(entry!.stack).toBeTruthy()
      })
    })
    
    describe('ログ', () => {
      it('1件のリクエストごとに、ルートの形・状態コード・利用者の番号を1行残す(メールアドレスは残さない)', async () => {
        const cookie = await loginAs('obs-agent@example.com', 'agent')
        const info = vi.spyOn(console, 'log').mockImplementation(() => {})
        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
        const res = await app.request('/api/tickets/999999', { headers: { cookie } }, env)
        expect(res.status).toBe(404)
    
        const entries = [...logged(info, 'request'), ...logged(warn, 'request')]
        // 404 は warn。route は番号ではなく、登録したときの形で残る
        expect(entries).toContainEqual(
          expect.objectContaining({ level: 'warn', status: 404, route: '/api/tickets/:id{[0-9]+}', method: 'GET' }),
        )
        expect(JSON.stringify(entries)).not.toContain('obs-agent@example.com')
      })
    
      it('D1 に届かないとき、ヘルスチェックは 503 を返してログに残す', async () => {
        const error = vi.spyOn(console, 'error').mockImplementation(() => {})
        const brokenDb = {
          prepare: () => {
            throw new Error('D1_ERROR: network connection lost')
          },
        } as unknown as D1Database
        const res = await app.request('/api/health', {}, { ...env, DB: brokenDb })
        expect(res.status).toBe(503)
        expect(await res.json()).toEqual({ status: 'error' })
        expect(logged(error, 'health_check_failed')).toHaveLength(1)
      })
    
      it('通知の再試行が残っているあいだは warn、最後の失敗は error で残す', async () => {
        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
        const error = vi.spyOn(console, 'error').mockImplementation(() => {})
        const run = async (attempts: number) => {
          const message = { id: `m${attempts}`, attempts, body: { kind: 'ticket_created', ticketId: 1 }, ack: vi.fn(), retry: vi.fn() }
          const batch = { queue: 'q', messages: [message] } as unknown as MessageBatch<NotificationMessage>
          // DB を壊して、handleMessage を必ず失敗させる
          const brokenEnv = { ...env, DB: { prepare: () => { throw new Error('D1 が応答しない') } } as unknown as D1Database }
          await processBatch(batch, brokenEnv, async () => {})
          return message
        }
        expect((await run(1)).retry).toHaveBeenCalled()
        expect(logged(warn, 'notification_retry')).toHaveLength(1)
        await run(4)
        expect(logged(error, 'notification_dead_lettered')).toMatchObject([{ attempts: 4, kind: 'ticket_created' }])
      })
    })

    </details>

    実行するコマンドは、これまでと同じです。

    npx wrangler types
    npm run typecheck
    npm test

    開発環境(Node.js 26 LTS・npm 11.20)では、型チェックが通り、テストは11ファイル92件すべて成功しました。npx wrangler dev でも、/api/health の応答に X-Request-Id が付くこと、壊れた JSON でのログインが {"error":"invalid_request","requestId":"…"} の 400 になること、/admin/ の下の存在しないページで問い合わせ番号つきの HTML が出ること、端末にオブジェクトの形でログが出ることを確かめました。Cloudflare の実環境での Workers Logs・Issues の画面は、この開発環境では確認していません。

    本番で困らないための注意点

    • ミドルウェアを登録する順番:withRequestId と accessLog は、すべてのルートより先に app.use します。後に書くと、先に応答したルートには付きません
    • /api の下の存在しない URL が 401 になる:コメントや添付ファイルのルートは /api の下でログイン確認をまとめてかけているため、ログインしていないと、存在しない URL でも 404 より先に 401 が返ります。番号が付くことは変わりません
    • Date.now() は計算中に進まない:Workers では、セキュリティ上の対策として Date.now() が最後の I/O(DB や外部への通信)の時刻を返し、計算のあいだは進みません。duration_ms は「I/O を待った時間」と考えてください
    • ログに個人情報や秘密を入れない:例外のメッセージに、外部サービスの応答(APIキーを含む URL など)がそのまま入ることがあります。errorFields を通す前に、外部への通信のエラーは中身を確かめてから投げるようにします
    • 本番運用で足したいもの:Issues から開発者への知らせ(webhook・チャット)や、外の監視サービスからのヘルスチェックの定期確認は、Cloudflare のアカウントと監視サービスでの設定が要るため、この連載では扱っていません。ログを7日より長く残したい場合は、外部への転送も検討します

    📰 出典:Cloudflare Docs「Security model」

    発注者向けメモ:障害のときの調べ方を決めるチェックリスト

    不具合は、テストをしても本番で起きることがあります。そのとき調べられるかは、作る段階でログとエラー処理を決めたかで大きく変わります。後から足すと全部のルートを見直すことになり、工数が増えやすい部分です。次の点を確認しておくと安心です。

    • ☐ 利用者がエラーを報告するとき、何を伝えればよいか(画面に問い合わせ番号が出るか)
    • ☐ ログに何を残し、何を残さないか(個人情報・パスワード・APIキーを残さない決まりがあるか)
    • ☐ ログを何日残すか。監査や調査のために、標準の保存期間より長く残す必要があるか
    • ☐ エラーが起きたとき、誰に・どの手段で知らせが届くか。夜間や休日はどうするか
    • ☐ 外から定期的に「動いているか」を確かめる仕組み(ヘルスチェックの監視)があるか

    開発会社への質問例です。

    • 「利用者から『エラーが出た』と連絡があったとき、どの情報があれば原因を調べられますか?」
    • 「ログの保存期間と費用は、利用者が増えたときにどう変わりますか?」

    工数が増えやすいのは、ログを長期間残す(外部の保存先への転送)、知らせの仕組みを当番表や夜間対応とつなぐ、監査のためにログの改ざん防止まで求める、といった場合です。金額の目安は、依頼先の見積もりで確認してください。

    まとめと次回予告

    この回では、ヘルプデスクに問い合わせ番号・アクセスログ・エラー応答の統一を入れ、Workers Logs と Issues を有効にしました。ポイントは次の3つです。

    • リクエストごとの番号を応答とログの両方に載せ、利用者の連絡からログの1行までたどれるようにする
    • ログは level と event を付けたオブジェクトで出し、個人情報は番号で残す
    • 想定外の例外は1か所(app.onError)で受け、利用者には番号だけ、原因はログにだけ残す

    次回(第11回)は「本番に公開する」です。staging と production の環境の分け方、wrangler secret での秘密情報の渡し方、D1 のマイグレーションの適用、費用の見当までを扱い、連載を締めくくります。

    この連載の記事一覧

    この記事は連載「Honoで作る社内ヘルプデスク」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら

      お問い合わせ


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      コメント

      コメント一覧 (2件)

      目次