@remote-logger/sdk 0.1.4 → 0.1.5

package/SKILL.md

@@ -22,10 +22,34 @@ You should default to placing logs early when investigating runtime issues. Don'
 - Correlating behavior across multiple services or processes (use `traceId`)
 - Monitoring a specific code path after a fix to verify it works
 
+## Best Practices
+
+**Use `withGroup()` to categorize logs — don't embed context in the message.**
+
+The `group` field is a queryable column in ClickHouse. When you prefix messages manually, you lose the ability to filter and aggregate by subsystem.
+
+```ts
+// Bad — context is buried in the message string, not queryable
+logger.info("[StorageService] Getting user");
+
+// Good — group is a structured, queryable field
+const log = logger.withGroup("StorageService");
+log.info("Getting user");
+
+// Also good — inline object form for one-off logs
+logger.info({ message: "Getting user", group: "StorageService" });
+```
+
+This lets you later query `WHERE group = 'StorageService'` or `GROUP BY group` to see log volume by subsystem.
+
+When placing logs across multiple files or modules during an investigation, create a scoped logger per module so logs are naturally organized. Use `withTraceId()` to correlate logs across a single request or operation, especially across services.
+
 ## SDK Quick Reference
 
 ### Setup (already done if the project uses this SDK)
 
+**Important:** Look for an existing logger instance in the project before creating a new one. Projects typically have a shared logger in a file like `logger.ts` or `lib/logger.ts` — import from there instead of calling `createLogger()` again.
+
 ```ts
 import { createLogger } from '@remote-logger/sdk';
 
@@ -49,15 +73,6 @@ logger.error(err as Error, { orderId: order.id });  // Error objects extract sta
 logger.fatal(new Error("database unreachable"));
 ```
 
-### Scoped Loggers (for grouping or tracing)
-
-```ts
-const authLogger = logger.withGroup("auth");       // all calls get group: "auth"
-const reqLogger = logger.withTraceId("req-abc");    // all calls get trace_id: "req-abc"
-```
-
-Use `group` to categorize logs by subsystem (e.g., "auth", "billing", "renderer"). Use `traceId` to correlate logs across a single request or operation, especially across services.
-
 ### Console Interception
 
 ```ts
@@ -111,7 +126,7 @@ group String            -- categorization (e.g., 'api/billing', 'main', 'rendere
 message String          -- log content
 stack Nullable(String)  -- stack trace
 error_type String       -- exception class name
-metadata Map(String, String) -- arbitrary key-value pairs
+metadata JSON              -- arbitrary structured data
 ```
 
 ## Do NOT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remote-logger/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "JavaScript SDK for Remote Logger",
   "main": "dist/index.js",
   "module": "dist/index.mjs",