feat(evlog): add deterministic minLevel for log api (#266)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: HugoRCD

.changeset/minlevel-log-threshold.md

@@ -0,0 +1,7 @@
+---
+'evlog': minor
+---
+
+Add `minLevel` for a deterministic severity threshold on the global `log` API and client `initLog`, plus `setMinLevel()` for runtime toggling in the browser. Orthogonal to probabilistic `sampling.rates`; request wide events from `useLogger` / `createLogger().emit()` are unchanged. Includes `isLevelEnabled()` helper and wiring for Nuxt, Vite, and Next.js.
+
+**2026-04-11** — Playground: interactive panel to try client `minLevel` / `setMinLevel` and trigger logs per level.

AGENTS.md

@@ -985,6 +985,8 @@ log.error({ action: 'payment', error: 'validation_failed' })
 
 Client logs output to the browser console with colored tags in development.
 
+`setMinLevel` is auto-imported in Nuxt (from `evlog/client`) — call it to change the client severity threshold at runtime (same as `initLog({ minLevel })`).
+
 #### Client Transport
 
 To send client logs to your server for centralized logging, enable the transport:

apps/docs/content/2.logging/4.client-logging.md

@@ -56,6 +56,14 @@ log.info({ action: 'app_init', path: window.location.pathname })
 
 The `log` object works anywhere in your client code: components, composables, event handlers.
 
+## Minimum level (`minLevel`)
+
+Use `initLog({ minLevel: 'warn' })` to keep the browser console quiet (warnings and errors only). Severity order: `debug` < `info` < `warn` < `error`. Default is `'debug'` (all levels).
+
+For a **debug toggle** without reloading, call `setMinLevel('debug')` or `setMinLevel('warn')` from `evlog/client` when the user opts in or out of verbose logs.
+
+`minLevel` applies to both console output and [server transport](#sending-logs-to-the-server) payloads.
+
 ## Two Call Signatures
 
 The `log` API accepts two forms depending on the context.
@@ -88,6 +96,8 @@ log.info('auth', 'User logged in')
 
 Both forms support four levels: `log.info()`, `log.warn()`, `log.error()`, and `log.debug()`.
 
+In the browser, `log.debug()` is emitted with `console.log` (not `console.debug`) so lines stay visible with the default DevTools **Info** filter; the structured event still has `level: 'debug'`.
+
 ## Identity Context
 
 Track which user generated a log with `setIdentity()`:
@@ -116,6 +126,7 @@ Identity fields are automatically merged into every log event until cleared. Thi
 | `enabled` | `true` | Enable or disable all client logging |
 | `console` | `true` | Output logs to the browser console |
 | `pretty` | `true` | Use colored, formatted console output |
+| `minLevel` | `'debug'` | Minimum severity: `debug` < `info` < `warn` < `error` |
 | `service` | `'client'` | Service name included in every log event |
 | `transport` | - | Send logs to a server endpoint (see below) |
 

apps/docs/content/3.core-concepts/1.configuration.md

@@ -32,6 +32,7 @@ initLogger({
   pretty: false,
   silent: false,
   stringify: true,
+  minLevel: 'info',
   sampling: { rates: { info: 10 }, keep: [{ status: 400 }] },
   drain: createAxiomDrain(),
 })
@@ -44,9 +45,17 @@ initLogger({
 | `pretty` | `boolean` | `true` in dev | Pretty print with tree formatting. Auto-detected based on `NODE_ENV` |
 | `silent` | `boolean` | `false` | Suppress console output. Events are still built, sampled, and passed to drains |
 | `stringify` | `boolean` | `true` | Emit JSON strings when `pretty` is disabled. Set to `false` for Cloudflare Workers |
+| `minLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'debug'` | Minimum severity for the global `log` API only (not `createLogger` / request wide events). Order: debug < info < warn < error |
 | `sampling` | `SamplingConfig` | `undefined` | Head and tail sampling configuration. See [Sampling](/core-concepts/sampling) |
 | `drain` | `(ctx: DrainContext) => void` | `undefined` | Drain callback for sending events to external services |
 
+### `minLevel` vs sampling
+
+- **`minLevel`** is a **hard threshold** on the simple `log.*` API: levels below the threshold are never emitted. It does **not** apply to wide events from `useLogger` / `createLogger().emit()` — use **`sampling.rates`** (and tail `keep`) for request volume.
+- **Head sampling** (`sampling.rates`) is **probabilistic** on what is already allowed by `minLevel` for simple logs.
+
+Evaluation order for `log.info` / `log.debug` / etc.: `enabled` → `minLevel` → head sampling → output.
+
 ### Environment Context
 
 The `env` option controls the fields included in every log event. Most values are auto-detected from environment variables and `package.json`.

apps/docs/skills/review-logging-patterns/SKILL.md

@@ -720,6 +720,7 @@ All options work in Nuxt (`evlog` key), Nitro (passed to `evlog()`), Next.js (`c
 | `include` | `string[]` | All routes | Route glob patterns to log |
 | `exclude` | `string[]` | None | Route patterns to exclude (takes precedence) |
 | `routes` | `Record<string, { service }>` | -- | Route-specific service names |
+| `minLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'debug'` | Hard threshold for the global `log` API and client `log` (not request wide events). Use `sampling.rates` for probabilistic volume on requests |
 | `sampling.rates` | `object` | -- | Head sampling: `{ info: 10, warn: 50 }` (0-100%) |
 | `sampling.keep` | `array` | -- | Tail sampling: `[{ status: 400 }, { duration: 1000 }]` |
 | `drain` | `(ctx) => void` | -- | Drain callback (Next.js, standalone) |

apps/playground/app/components/playground/MinLevelPanel.vue

@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import type { LogLevel } from 'evlog'
+import { log, setMinLevel } from 'evlog/client'
+
+const levels: LogLevel[] = ['debug', 'info', 'warn', 'error']
+
+const minLevel = ref<LogLevel>('debug')
+
+const order: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+}
+
+function passes(level: LogLevel): boolean {
+  return order[level] >= order[minLevel.value]
+}
+
+function applyMinLevel(level: LogLevel) {
+  minLevel.value = level
+  setMinLevel(level)
+}
+
+function emitAt(level: LogLevel) {
+  const payload = { panel: 'min-level', ts: Date.now() }
+  if (level === 'debug') {
+    log.debug(payload)
+  } else if (level === 'info') {
+    log.info(payload)
+  } else if (level === 'warn') {
+    log.warn('playground', 'warn sample')
+  } else {
+    log.error('playground', 'error sample')
+  }
+}
+
+onMounted(() => {
+  const raw = useRuntimeConfig().public.evlog as { minLevel?: LogLevel } | undefined
+  const fromConfig = raw?.minLevel
+  if (fromConfig && levels.includes(fromConfig)) {
+    minLevel.value = fromConfig
+    setMinLevel(fromConfig)
+  }
+})
+</script>
+
+<template>
+  <ClientOnly>
+    <div class="max-w-3xl space-y-6">
+      <div
+        class="rounded-lg border border-[var(--ui-border)] bg-elevated p-5 space-y-4"
+      >
+        <div>
+          <p class="text-xs font-medium text-highlighted uppercase tracking-wide">
+            Minimum level
+          </p>
+          <p class="text-xs text-muted mt-1 leading-relaxed">
+            Only the global client <code class="text-[11px]">log.*</code> API is filtered. Open DevTools and watch the console: levels below the threshold produce no output and no transport when ingest is enabled.
+          </p>
+        </div>
+
+        <div class="flex flex-wrap gap-2">
+          <UButton
+            v-for="lvl in levels"
+            :key="lvl"
+            size="sm"
+            :variant="minLevel === lvl ? 'solid' : 'outline'"
+            :color="minLevel === lvl ? 'primary' : 'neutral'"
+            @click="applyMinLevel(lvl)"
+          >
+            {{ lvl }}
+          </UButton>
+        </div>
+
+        <p class="text-[11px] text-muted leading-relaxed">
+          <span class="text-highlighted">Passes:</span>
+          {{ levels.filter(l => passes(l)).join(', ') }}
+        </p>
+        <p class="text-[11px] text-muted leading-relaxed">
+          <code class="text-[11px]">log.debug()</code> uses <code class="text-[11px]">console.log</code> in the browser so lines show with the default console filter (payload still has <code class="text-[11px]">level: &quot;debug&quot;</code>).
+        </p>
+      </div>
+
+      <div
+        class="rounded-lg border border-[var(--ui-border)] bg-elevated p-5 space-y-4"
+      >
+        <p class="text-xs font-medium text-highlighted uppercase tracking-wide">
+          Trigger logs
+        </p>
+        <div class="flex flex-wrap gap-2">
+          <UButton
+            v-for="lvl in levels"
+            :key="`emit-${lvl}`"
+            size="sm"
+            variant="soft"
+            :color="lvl === 'error' ? 'error' : lvl === 'warn' ? 'warning' : lvl === 'info' ? 'primary' : 'neutral'"
+            @click="emitAt(lvl)"
+          >
+            log.{{ lvl }}()
+          </UButton>
+        </div>
+        <p class="text-[11px] text-muted">
+          Set minimum to <code class="text-[11px]">warn</code>, then trigger <code class="text-[11px]">log.info</code> — nothing should appear. Switch back to <code class="text-[11px]">debug</code> and trigger again to verify.
+        </p>
+      </div>
+    </div>
+    <template #fallback>
+      <p class="text-sm text-muted">
+        Loading…
+      </p>
+    </template>
+  </ClientOnly>
+</template>

apps/playground/app/config/tests.config.ts

@@ -51,6 +51,15 @@ function makeDrainEvent(action: string, extra?: Record<string, unknown>) {
 
 export const testConfig = {
   sections: [
+    {
+      id: 'min-level',
+      label: 'Min level',
+      icon: 'i-lucide-sliders-horizontal',
+      title: 'Minimum log level (client)',
+      description:
+        'Deterministic filter for the client `log` API: choose a minimum severity, trigger each level, and confirm blocked lines never reach the console or ingest. Use `setMinLevel` at runtime without reload.',
+      tests: [],
+    } as TestSection,
     {
       id: 'client-logging',
       label: 'Client Logging',

apps/playground/app/pages/index.vue

@@ -46,7 +46,11 @@ const currentSection = computed(() =>
         :title="currentSection.title"
         :description="currentSection.description"
       >
-        <div class="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+        <PlaygroundMinLevelPanel v-if="currentSection.id === 'min-level'" />
+        <div
+          v-else
+          class="grid gap-4 md:grid-cols-2 xl:grid-cols-3"
+        >
           <PlaygroundTestCard
             v-for="test in currentSection.tests"
             :key="test.id"

bun.lock

@@ -1 +1 @@
-export { initLog, log, setIdentity, clearIdentity } from './runtime/client/log'
+export { initLog, log, setIdentity, clearIdentity, setMinLevel } from './runtime/client/log'