feat: add telemetry foundation for APM integration

Add shared createLogger utility and client-side telemetry sinks so
debug console.log can be replaced with environment-aware logging.
Sentry hooks are stubbed for web (window.Sentry) and API (SENTRY_DSN)
until DSN is configured. Document observability env vars in .env.example.

Author: cursoragent

.env.example

@@ -31,4 +31,12 @@ LOG_LEVEL=debug
 
 # PWA設定
 # アプリケーション名（マニフェストとメタデータに使用）
-NEXT_PUBLIC_APP_NAME=Sonory
+NEXT_PUBLIC_APP_NAME=Sonory
+
+# オブザーバビリティ（APM）
+# ブラウザ + Next.js: https://sentry.io でプロジェクト作成後に設定
+NEXT_PUBLIC_SENTRY_DSN=
+# Cloudflare Workers API: wrangler secret put SENTRY_DSN --env production
+SENTRY_DSN=
+# 本番以外で Sentry へ送る場合は true（通常は未設定で development はローカルのみ）
+# NEXT_PUBLIC_SENTRY_ENABLED=false

apps/api/src/middleware/monitoring.ts

@@ -1,6 +1,7 @@
 import type { Context, Next } from "hono"
 import type { Env } from "../index"
 import { logger } from "../utils/logger"
+import { captureException } from "../utils/telemetry"
 
 /**
  * モニタリング・ログ基盤ミドルウェア
@@ -38,10 +39,9 @@ export async function errorTracking(
 
       logger.error("Unhandled error occurred", errorDetails)
 
-      // TODO Phase 2以降: Sentryに送信
-      // if (c.env.SENTRY_DSN) {
-      //   await sendToSentry(errorDetails)
-      // }
+      if (c.env.SENTRY_DSN) {
+         await captureException(error, errorDetails)
+      }
 
       // エラーを再スロー（エラーハンドラーミドルウェアで処理）
       throw error

apps/api/src/types/env.ts

@@ -9,4 +9,6 @@ export interface Env {
    SUPABASE_SERVICE_KEY?: string
    PYTHON_AUDIO_ANALYZER_URL: string
    PYTHON_AUDIO_ANALYZER_TIMEOUT: string
+   /** Sentry DSN（`wrangler secret put SENTRY_DSN` で設定） */
+   SENTRY_DSN?: string
 }

apps/api/src/utils/telemetry.ts

@@ -0,0 +1,31 @@
+import type { LogContext } from "@sonory/utils"
+
+/**
+ * Workers 向けのエラー転送先。
+ *
+ * @description
+ * Phase 2: `@sentry/cloudflare` 導入後に実装を差し替える。
+ */
+export async function captureException(
+   error: unknown,
+   context?: LogContext,
+): Promise<void> {
+   // Sentry DSN 設定後:
+   // import * as Sentry from "@sentry/cloudflare"
+   // Sentry.captureException(error, { extra: context })
+   void error
+   void context
+}
+
+/**
+ * 構造化メトリクスを Workers Analytics Engine へ送るためのプレースホルダー。
+ */
+export function recordMetric(
+   name: string,
+   value: number,
+   tags?: LogContext,
+): void {
+   void name
+   void value
+   void tags
+}

apps/web/package.json

@@ -29,6 +29,7 @@
       "@mapbox/mapbox-gl-geocoder": "^5.1.2",
       "@opennextjs/cloudflare": "^1.19.11",
       "@sonory/shared-types": "*",
+      "@sonory/utils": "*",
       "@supabase/supabase-js": "^2.108.0",
       "@tanstack/react-query": "^5.101.0",
       "framer-motion": "^12.40.0",

apps/web/src/lib/telemetry/createClientLogger.ts

@@ -0,0 +1,50 @@
+import { createLogger, type Logger } from "@sonory/utils"
+
+import { createConsoleSink } from "./sinks/consoleSink"
+import { createSentrySink } from "./sinks/sentrySink"
+
+const isDevelopment = process.env.NODE_ENV === "development"
+
+/**
+ * ブラウザ向けロガーを生成する。
+ *
+ * @description
+ * - `debug` / `info`: 開発環境のみコンソール出力
+ * - `warn` / `error`: 本番では Sentry へ転送（DSN 設定時）
+ * - 位置情報・音声 URL など PII は context に載せないこと
+ *
+ * @param namespace - ログの発生元（例: `"SoundPinMarkers"`）
+ * @returns 名前空間付きロガー
+ *
+ * @example
+ * ```ts
+ * const log = createClientLogger("recording")
+ * log.debug("Recorder started")
+ * log.error("Upload failed", { code: "NETWORK_ERROR" })
+ * ```
+ */
+export function createClientLogger(namespace: string): Logger {
+   const consoleSink = createConsoleSink()
+   const sentrySink = createSentrySink(namespace)
+
+   return createLogger({
+      namespace,
+      minLevel: isDevelopment ? "debug" : "warn",
+      sinks: {
+         debug: isDevelopment ? consoleSink.debug : undefined,
+         info: isDevelopment ? consoleSink.info : sentrySink.info,
+         warn: (message, context) => {
+            if (isDevelopment) {
+               consoleSink.warn(message, context)
+            }
+            sentrySink.warn(message, context)
+         },
+         error: (message, context) => {
+            if (isDevelopment) {
+               consoleSink.error(message, context)
+            }
+            sentrySink.error(message, context)
+         },
+      },
+   })
+}

apps/web/src/lib/telemetry/index.ts

@@ -0,0 +1 @@
+export { createClientLogger } from "./createClientLogger"

apps/web/src/lib/telemetry/sinks/consoleSink.ts

@@ -0,0 +1,26 @@
+import type { LogContext, LogLevel } from "@sonory/utils"
+
+/**
+ * 開発環境向けのコンソール出力シンク。
+ */
+export function createConsoleSink(): Readonly<
+   Record<LogLevel, (message: string, context?: LogContext) => void>
+> {
+   const format = (message: string, context?: LogContext): string =>
+      context === undefined ? message : `${message} ${JSON.stringify(context)}`
+
+   return {
+      debug: (message, context) => {
+         console.debug(format(message, context))
+      },
+      info: (message, context) => {
+         console.info(format(message, context))
+      },
+      warn: (message, context) => {
+         console.warn(format(message, context))
+      },
+      error: (message, context) => {
+         console.error(format(message, context))
+      },
+   }
+}

apps/web/src/lib/telemetry/sinks/sentrySink.ts

@@ -0,0 +1,91 @@
+import type { LogContext } from "@sonory/utils"
+
+/**
+ * Sentry SDK が提供する最小インターフェース。
+ *
+ * @description
+ * `@sentry/nextjs` 導入後に `window.Sentry` へバインドされる想定。
+ */
+interface SentryClient {
+   addBreadcrumb(breadcrumb: {
+      category: string
+      message: string
+      level?: "debug" | "info" | "warning" | "error"
+      data?: Record<string, unknown>
+   }): void
+   captureException(
+      error: unknown,
+      context?: { extra?: Record<string, unknown> },
+   ): void
+   captureMessage(
+      message: string,
+      context?: {
+         level?: "warning" | "error"
+         extra?: Record<string, unknown>
+      },
+   ): void
+}
+
+declare global {
+   interface Window {
+      Sentry?: SentryClient
+   }
+}
+
+function getSentryClient(): SentryClient | undefined {
+   if (typeof window === "undefined") {
+      return undefined
+   }
+
+   return window.Sentry
+}
+
+/**
+ * Sentry 向けのブレッドクラム・エラー転送シンク。
+ *
+ * @description
+ * DSN 未設定時は no-op。APM 導入後も呼び出し側の変更は不要。
+ */
+export function createSentrySink(namespace: string): {
+   info(message: string, context?: LogContext): void
+   warn(message: string, context?: LogContext): void
+   error(message: string, context?: LogContext): void
+} {
+   const toBreadcrumb = (
+      level: "info" | "warning" | "error",
+      message: string,
+      context?: LogContext,
+   ): void => {
+      const sentry = getSentryClient()
+      if (!sentry) {
+         return
+      }
+
+      sentry.addBreadcrumb({
+         category: namespace,
+         message,
+         level: level === "warning" ? "warning" : level,
+         data: context,
+      })
+   }
+
+   return {
+      info: (message, context) => {
+         toBreadcrumb("info", message, context)
+      },
+      warn: (message, context) => {
+         toBreadcrumb("warning", message, context)
+         getSentryClient()?.captureMessage(message, {
+            level: "warning",
+            extra: context,
+         })
+      },
+      error: (message, context) => {
+         toBreadcrumb("error", message, context)
+         getSentryClient()?.captureMessage(message, {
+            level: "error",
+            extra: context,
+         })
+      },
+   }
+}