Skip to content

Commit d16bae6

Browse files
patricklafrancepatricklafrance
authored
docs: update SKILL.md and add API and patterns reference documentation for @workleap/logging (#59)
1 parent 88c5660 commit d16bae6

3 files changed

Lines changed: 234 additions & 217 deletions

File tree

‎agent-skills/workleap-logging/SKILL.md‎

Lines changed: 21 additions & 217 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,16 @@
11
---
22
name: workleap-logging
33
description: |
4-
Guide for Workleap's logging library (@workleap/logging) that provides structured, composable logging for frontend TypeScript applications.
4+
Guide for @workleap/logging, a structured logging library for Workleap frontend TypeScript applications.
55
66
Use this skill when:
7-
(1) Setting up logging in a Workleap frontend application
8-
(2) Creating or configuring loggers (BrowserConsoleLogger, CompositeLogger)
9-
(3) Understanding log levels (debug, information, warning, error, critical)
10-
(4) Building complex log entries with chained segments (withText, withObject, withError)
11-
(5) Using logging scopes to group related log entries
12-
(6) Styling log output in browser console
13-
(7) Composing multiple loggers to send logs to different destinations
14-
(8) Filtering logs by severity level
15-
(9) Integrating logging with LogRocket or other telemetry tools
16-
(10) Reviewing logging-related changes in pull requests
17-
(11) Questions about logging best practices specific to wl-logging
7+
(1) Setting up or configuring @workleap/logging loggers (BrowserConsoleLogger, CompositeLogger)
8+
(2) Using @workleap/logging API: log levels, chained segments, scopes, styled output
9+
(3) Composing or filtering @workleap/logging loggers for multi-destination logging
10+
(4) Integrating @workleap/logging with LogRocket via CompositeLogger
11+
(5) Reviewing PRs or troubleshooting @workleap/logging usage
12+
metadata:
13+
version: 1.1
1814
---
1915

2016
# Workleap Logging (@workleap/logging)
@@ -54,44 +50,10 @@ const logger = useLogger();
5450
(logger as RootLogger).startScope("User signup");
5551
```
5652

57-
## API Reference
53+
## Chained Segments
5854

59-
### BrowserConsoleLogger
55+
Build complex log entries by chaining segments. **Always complete the chain with a log level method** (`.debug()`, `.error()`, etc.) or nothing is output.
6056

61-
```ts
62-
import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";
63-
64-
// Basic usage
65-
const logger = new BrowserConsoleLogger();
66-
67-
// With minimum log level
68-
const logger = new BrowserConsoleLogger({ logLevel: LogLevel.information });
69-
```
70-
71-
### CompositeLogger
72-
73-
```ts
74-
import { BrowserConsoleLogger, CompositeLogger } from "@workleap/logging";
75-
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
76-
77-
const logger = new CompositeLogger([
78-
new BrowserConsoleLogger(),
79-
new LogRocketLogger()
80-
]);
81-
```
82-
83-
### Logger Methods
84-
85-
**Simple logging:**
86-
```ts
87-
logger.debug("message");
88-
logger.information("message");
89-
logger.warning("message"); // or logger.warn("message")
90-
logger.error("message");
91-
logger.critical("message");
92-
```
93-
94-
**Chained segments (complete chain with log method):**
9557
```ts
9658
logger
9759
.withText("Processing order")
@@ -100,175 +62,6 @@ logger
10062
.error();
10163
```
10264

103-
**Styled text:**
104-
```ts
105-
logger.withText("Success", {
106-
style: { color: "green", fontWeight: "bold" }
107-
}).information();
108-
```
109-
110-
**Line breaks:**
111-
```ts
112-
logger
113-
.withText("Line 1")
114-
.withLineChange()
115-
.withText("Line 2")
116-
.debug();
117-
```
118-
119-
### Scopes
120-
121-
```ts
122-
const scope = logger.startScope("User signup");
123-
124-
scope.information("Form loaded");
125-
scope.debug("Validating...");
126-
scope.withText("Failed").withError(err).error();
127-
128-
// Output all scope entries
129-
scope.end();
130-
131-
// Or dismiss without output
132-
scope.end({ dismiss: true });
133-
```
134-
135-
**Styled scope labels:**
136-
```ts
137-
// At creation
138-
const scope = logger.startScope("Label", {
139-
labelStyle: { backgroundColor: "purple", color: "white" }
140-
});
141-
142-
// At end (useful for status-based styling)
143-
scope.end({
144-
labelStyle: { backgroundColor: "green", color: "white" }
145-
});
146-
```
147-
148-
### createCompositeLogger
149-
150-
Factory function to create a `CompositeLogger` instance from Workleap libraries standard logging API.
151-
152-
```ts
153-
import { createCompositeLogger, BrowserConsoleLogger } from "@workleap/logging";
154-
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
155-
156-
const logger = createCompositeLogger(false, [new BrowserConsoleLogger(), new LogRocketLogger()]);
157-
```
158-
159-
**Parameters:**
160-
- `verbose`: Whether debug information should be logged. If no loggers are provided, creates with a `BrowserConsoleLogger` by default.
161-
- `loggers`: Array of loggers to create the `CompositeLogger` with.
162-
163-
## LogRocket Integration
164-
165-
By default, LogRocket session replays exclude console output. To send log entries to LogRocket, use `LogRocketLogger` from `@workleap/telemetry` or `@workleap/logrocket`:
166-
167-
```ts
168-
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
169-
170-
const logger = new LogRocketLogger();
171-
logger.debug("Application started!");
172-
```
173-
174-
Use `CompositeLogger` to send logs to both browser console and LogRocket:
175-
176-
```ts
177-
import { BrowserConsoleLogger, CompositeLogger } from "@workleap/logging";
178-
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
179-
180-
const logger = new CompositeLogger([
181-
new BrowserConsoleLogger(),
182-
new LogRocketLogger()
183-
]);
184-
185-
logger.debug("Application started!"); // Processed by both loggers
186-
```
187-
188-
## Common Patterns
189-
190-
### Application logger setup
191-
192-
```ts
193-
import { BrowserConsoleLogger, CompositeLogger, LogLevel } from "@workleap/logging";
194-
195-
const isDev = process.env.NODE_ENV === "development";
196-
197-
const logger = new BrowserConsoleLogger({
198-
logLevel: isDev ? LogLevel.debug : LogLevel.information
199-
});
200-
```
201-
202-
### Error logging
203-
204-
```ts
205-
try {
206-
await processOrder(orderId);
207-
} catch (error) {
208-
logger
209-
.withText("Failed to process order")
210-
.withObject({ orderId })
211-
.withError(error as Error)
212-
.error();
213-
}
214-
```
215-
216-
### Feature/operation scoping
217-
218-
```ts
219-
async function registerModule(moduleName: string) {
220-
const scope = logger.startScope(`${moduleName} registration`);
221-
222-
try {
223-
scope.debug("Registering routes...");
224-
await registerRoutes();
225-
scope.debug("Routes registered");
226-
227-
scope.debug("Fetching data...");
228-
await fetchData();
229-
scope.debug("Data loaded");
230-
231-
scope.end({ labelStyle: { color: "green" } });
232-
} catch (error) {
233-
scope.withText("Registration failed").withError(error as Error).error();
234-
scope.end({ labelStyle: { color: "red" } });
235-
throw error;
236-
}
237-
}
238-
```
239-
240-
### Multi-destination logging
241-
242-
```ts
243-
import { BrowserConsoleLogger, CompositeLogger, LogLevel } from "@workleap/logging";
244-
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
245-
246-
const logger = new CompositeLogger([
247-
new BrowserConsoleLogger({
248-
logLevel: LogLevel.error
249-
}),
250-
new LogRocketLogger({
251-
logLevel: LogLevel.debug
252-
})
253-
]);
254-
```
255-
256-
## Log Level Guidelines
257-
258-
| Environment | Recommended Level |
259-
|-------------|-------------------|
260-
| Development | `debug` |
261-
| Production | `information` |
262-
263-
## PR Review Checklist
264-
265-
When reviewing logging changes:
266-
- Verify appropriate log levels (debug for diagnostics, error for failures)
267-
- Check that errors include context (withObject) and stack traces (withError)
268-
- Ensure scopes are properly ended (end() or end({ dismiss: true }))
269-
- Confirm no sensitive data in log messages
270-
- Verify CompositeLogger filters are set per environment
271-
27265
## Common Mistakes
27366

27467
1. **Forgetting to call log method**: Chained segments require `.debug()`, `.error()`, etc. to output
@@ -277,3 +70,14 @@ When reviewing logging changes:
27770
4. **Logging sensitive data**: Never log passwords, tokens, or PII
27871
5. **Missing error context**: Always include `withObject()` for relevant data and `withError()` for exceptions
27972
6. **Calling startScope on a non-RootLogger**: Only `RootLogger` instances can start scopes. When using `useLogger()` from Squide, cast to `RootLogger` first: `(logger as RootLogger).startScope("Label")`
73+
74+
## Reference Guide
75+
76+
For detailed documentation beyond the patterns above, consult:
77+
78+
- **`references/api.md`** — Logger constructors, all methods (styled text, line breaks), scope API, createCompositeLogger, log level guidelines
79+
- **`references/patterns.md`** — Common patterns (app setup, error logging, scoping, multi-destination), LogRocket integration, PR review checklist
80+
81+
## Maintenance Note
82+
83+
Body budget: ~75 lines. API details and common patterns moved to references/ since they are single-function examples and straightforward procedural content. Core concepts, chained segments, and common mistakes retained as they are the primary use cases and non-obvious pitfalls. New content goes in the appropriate `references/` file — only add to the body if it is a critical pattern needed in nearly every conversation.

‎agent-skills/workleap-logging/references/api.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# API Reference
2+
3+
## BrowserConsoleLogger
4+
5+
```ts
6+
import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";
7+
8+
// Basic usage
9+
const logger = new BrowserConsoleLogger();
10+
11+
// With minimum log level
12+
const logger = new BrowserConsoleLogger({ logLevel: LogLevel.information });
13+
```
14+
15+
## CompositeLogger
16+
17+
```ts
18+
import { BrowserConsoleLogger, CompositeLogger } from "@workleap/logging";
19+
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
20+
21+
const logger = new CompositeLogger([
22+
new BrowserConsoleLogger(),
23+
new LogRocketLogger()
24+
]);
25+
```
26+
27+
## Logger Methods
28+
29+
**Simple logging:**
30+
```ts
31+
logger.debug("message");
32+
logger.information("message");
33+
logger.warning("message");
34+
logger.error("message");
35+
logger.critical("message");
36+
```
37+
38+
**Chained segments (complete chain with log method):**
39+
```ts
40+
logger
41+
.withText("Processing order")
42+
.withObject({ orderId: 123 })
43+
.withError(new Error("Failed"))
44+
.error();
45+
```
46+
47+
**Styled text:**
48+
```ts
49+
logger.withText("Success", {
50+
style: { color: "green", fontWeight: "bold" }
51+
}).information();
52+
```
53+
54+
**Line breaks:**
55+
```ts
56+
logger
57+
.withText("Line 1")
58+
.withLineChange()
59+
.withText("Line 2")
60+
.debug();
61+
```
62+
63+
## Scopes
64+
65+
```ts
66+
const scope = logger.startScope("User signup");
67+
68+
scope.information("Form loaded");
69+
scope.debug("Validating...");
70+
scope.withText("Failed").withError(err).error();
71+
72+
// Output all scope entries
73+
scope.end();
74+
75+
// Or dismiss without output
76+
scope.end({ dismiss: true });
77+
```
78+
79+
**Styled scope labels:**
80+
```ts
81+
// At creation
82+
const scope = logger.startScope("Label", {
83+
labelStyle: { backgroundColor: "purple", color: "white" }
84+
});
85+
86+
// At end (useful for status-based styling)
87+
scope.end({
88+
labelStyle: { backgroundColor: "green", color: "white" }
89+
});
90+
```
91+
92+
## createCompositeLogger
93+
94+
Factory function to create a `CompositeLogger` instance from Workleap libraries standard logging API.
95+
96+
```ts
97+
import { createCompositeLogger, BrowserConsoleLogger } from "@workleap/logging";
98+
import { LogRocketLogger } from "@workleap/telemetry"; // or from "@workleap/logrocket"
99+
100+
const logger = createCompositeLogger(false, [new BrowserConsoleLogger(), new LogRocketLogger()]);
101+
```
102+
103+
**Parameters:**
104+
- `verbose`: Whether debug information should be logged. If no loggers are provided, creates with a `BrowserConsoleLogger` by default.
105+
- `loggers`: Array of loggers to create the `CompositeLogger` with.
106+
107+
## Log Level Guidelines
108+
109+
| Environment | Recommended Level |
110+
|-------------|-------------------|
111+
| Development | `debug` |
112+
| Production | `information` |

0 commit comments

Comments
 (0)