社内ヘルプデスクは、登録・一覧・コメント・通知・期限超過の検知・管理画面・型つきの呼び出しまでそろいました。本番に出す前に決めておきたいのが、動かしたあとに「何が起きたか」を後から追える仕組み、つまりログとエラー処理・監視です。
「社員から『ヘルプデスクでエラーが出た』と連絡が来ても、いつ・どの画面で・何が起きたのか分からない。原因を調べられるようにしておくには、何を作っておけばいいの?」
結論から言うと、リクエストごとに「問い合わせ番号(リクエスト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日 |
| Issues | open beta の期間中は無料 | open beta の期間中は無料 |
公式ドキュメントには、2026年12月1日から Workers Logs の料金が Cloudflare Observability の料金に移ると書かれています。本番で使う前に、最新の料金ページを確かめてください。head_sampling_rate を 0.1(10件に1件)に下げるとログは減りますが、問い合わせ番号で探しても見つからないことが起きます。社内ツールの規模なら、まずはすべて残す設定で足りることが多いです。
📰 出典:Cloudflare Docs「Workers Logs」
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回です。連載のほかの回は次のとおりです(連載の一覧ページ)。
- 【Honoで作る社内ヘルプデスク 第0回】連載の全体像と、Hono+Cloudflare Workersの雛形を動かす
- 【Honoで作る社内ヘルプデスク 第1回】チケット登録APIを作る:D1のマイグレーションとZodの入力チェック
- 【Honoで作る社内ヘルプデスク 第2回】チケットの一覧と状態遷移を作る:ページングと「戻せない状態」のルール
- 【Honoで作る社内ヘルプデスク 第3回】ログインと権限を付ける:パスワードの保存・Cookie・「社員/担当者/管理者」の線引き
- 【Honoで作る社内ヘルプデスク 第4回】添付ファイルを R2 に保存する:種類・大きさの制限とダウンロード権限
- 【Honoで作る社内ヘルプデスク 第5回】通知メールをCloudflare Queuesで非同期に送る
- 【Honoで作る社内ヘルプデスク 第6回】コメントと担当者の割り当て、変更の履歴を残す
- 【Honoで作る社内ヘルプデスク 第7回】期限超過をCron Triggersで検知する:対応期限(SLA)と二重通知の防ぎ方
- 【Honoで作る社内ヘルプデスク 第8回】管理画面をHonoのJSXで作る:サーバー側描画とフォーム、CSRF対策
- 【Honoで作る社内ヘルプデスク 第9回】hono/clientで型安全にAPIを呼ぶ:ルートの型を共有して呼び間違いを防ぐ
- 【Honoで作る社内ヘルプデスク 第10回】ログとエラー処理・監視:Workers Logsと問い合わせ番号で「何が起きたか」を追えるようにする(この記事)









コメント
コメント一覧 (2件)
[…] 【Honoで作る社内ヘルプデスク 第10回】ログとエラー処理・監視:Workers Logs… […]
[…] 【Honoで作る社内ヘルプデスク 第10回】ログとエラー処理・監視:Workers Logs… […]