Skip to content

Commit 6859880

Browse files
claveryclavery
authored
@W-20936580 feat: add logs topic for retrieving and monitoring instance logs (#77)
* wip * wip * add logs get command, docs, and skill - logs get: one-shot log retrieval with filtering (--since, --level, --search) - docs/cli/logs.md: CLI reference for logs topic - plugins/b2c-cli/skills/b2c-logs: agent-friendly skill for logs commands * remove accidentally committed log file * add --level and --search filtering to logs tail command - Extract shared formatting and filtering utilities to utils/logs/ - Add --level flag to filter by log level (ERROR, WARN, etc.) - Add --search (-g) flag for case-insensitive text search - Update docs and skill file with new tail examples * add docs for downloading full log files via webdav Show how to use b2c webdav get with the log filename from entry headers to retrieve complete log files for deeper investigation. * condense log file download docs, add JSON example - Shorten download section to single command example - Reference b2c-cli:b2c-webdav skill by name - Show actual JSON output with file field visible
1 parent 6e82d3d commit 6859880

20 files changed

Lines changed: 3508 additions & 0 deletions

File tree

‎.changeset/log-tailing-feature.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
'@salesforce/b2c-cli': minor
3+
'@salesforce/b2c-tooling-sdk': minor
4+
---
5+
6+
Add log tailing and listing commands for viewing B2C Commerce instance logs
7+
8+
New CLI commands:
9+
- `b2c logs list` - List log files with filtering by prefix and sorting
10+
- `b2c logs tail` - Real-time log tailing with colored output and path normalization
11+
12+
New SDK functions in `@salesforce/b2c-tooling-sdk/operations/logs`:
13+
- `listLogFiles()` - List and filter log files
14+
- `tailLogs()` - Continuous log tailing with callbacks
15+
- `getRecentLogs()` - One-shot retrieval of recent log entries
16+
- `createPathNormalizer()` - Convert remote paths to local for IDE click-to-open

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ const guideSidebar = [
3131
{ text: 'Overview', link: '/cli/' },
3232
{ text: 'Code Commands', link: '/cli/code' },
3333
{ text: 'Job Commands', link: '/cli/jobs' },
34+
{ text: 'Logs Commands', link: '/cli/logs' },
3435
{ text: 'Sites Commands', link: '/cli/sites' },
3536
{ text: 'WebDAV Commands', link: '/cli/webdav' },
3637
{ text: 'ODS Commands', link: '/cli/ods' },

‎docs/cli/logs.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
---
2+
description: Commands for retrieving and monitoring log files on B2C Commerce instances.
3+
---
4+
5+
# Logs Commands
6+
7+
Commands for retrieving and monitoring log files on B2C Commerce instances. These commands provide convenient access to instance logs without needing to manually navigate WebDAV.
8+
9+
## Authentication
10+
11+
All logs commands require WebDAV credentials. See the [WebDAV Authentication](/cli/webdav#authentication) section for details on Basic Auth and OAuth options.
12+
13+
---
14+
15+
## b2c logs get
16+
17+
Get recent log entries from a B2C Commerce instance. This command is designed for one-shot log retrieval with filtering options, suitable for both human use and programmatic/agent access.
18+
19+
### Usage
20+
21+
```bash
22+
b2c logs get
23+
```
24+
25+
### Flags
26+
27+
| Flag | Description | Default |
28+
|------|-------------|---------|
29+
| `--filter`, `-f` | Log prefixes to filter (can specify multiple) | `error`, `customerror` |
30+
| `--count`, `-n` | Maximum number of entries to retrieve | `20` |
31+
| `--since` | Only show entries after this time (e.g., "5m", "1h", "2d", or ISO 8601) | - |
32+
| `--level` | Filter by log level (can specify multiple): ERROR, WARN, INFO, DEBUG, FATAL, TRACE | - |
33+
| `--search`, `-g` | Filter entries containing this text (case-insensitive) | - |
34+
| `--cartridge-path` | Override cartridge path for path normalization | Auto-discovered |
35+
| `--no-normalize` | Disable automatic path normalization | `false` |
36+
| `--no-color` | Disable colored output | `false` |
37+
| `--json` | Output as JSON | `false` |
38+
39+
### Examples
40+
41+
```bash
42+
# Get recent logs (default: error and customerror, last 20 entries)
43+
b2c logs get
44+
45+
# Get more entries
46+
b2c logs get --count 50
47+
48+
# Get logs from specific types
49+
b2c logs get --filter error --filter debug --filter warn
50+
51+
# Filter by time - last 5 minutes
52+
b2c logs get --since 5m
53+
54+
# Filter by time - last 2 hours
55+
b2c logs get --since 2h
56+
57+
# Filter by time - specific timestamp
58+
b2c logs get --since "2026-01-25T10:00:00"
59+
60+
# Filter by log level
61+
b2c logs get --level ERROR --level FATAL
62+
63+
# Search for specific text
64+
b2c logs get --search "OrderMgr"
65+
66+
# Combined filters with JSON output
67+
b2c logs get --since 1h --level ERROR --search "PaymentProcessor" --json
68+
```
69+
70+
### Output
71+
72+
Human-readable output displays entries with colored log levels:
73+
74+
```
75+
ERROR [2026-01-25 10:30:45.123 GMT] [customerror-blade0-1-appserver-20260125.log]
76+
Error in OrderMgr.placeOrder at /app_storefront/cartridge/scripts/checkout.js:42
77+
78+
WARN [2026-01-25 10:29:12.456 GMT] [error-blade0-1-appserver-20260125.log]
79+
Slow query detected in product search
80+
```
81+
82+
JSON output (`--json`) returns:
83+
84+
```json
85+
{
86+
"count": 2,
87+
"entries": [
88+
{
89+
"file": "customerror-blade0-1-appserver-20260125.log",
90+
"level": "ERROR",
91+
"timestamp": "2026-01-25 10:30:45.123 GMT",
92+
"message": "Error in OrderMgr.placeOrder at ./cartridges/app_storefront/cartridge/scripts/checkout.js:42",
93+
"raw": "[2026-01-25 10:30:45.123 GMT] ERROR ... (full raw line)"
94+
}
95+
]
96+
}
97+
```
98+
99+
### Path Normalization
100+
101+
By default, file paths in log messages are converted from server paths to local paths for IDE click-to-open functionality. The command auto-discovers your local cartridge directory structure.
102+
103+
Use `--no-normalize` to disable this feature, or `--cartridge-path` to specify a custom cartridge location.
104+
105+
---
106+
107+
## b2c logs list
108+
109+
List log files available on a B2C Commerce instance.
110+
111+
### Usage
112+
113+
```bash
114+
b2c logs list
115+
```
116+
117+
### Flags
118+
119+
| Flag | Description | Default |
120+
|------|-------------|---------|
121+
| `--filter`, `-f` | Filter by log prefix (can specify multiple) | All logs |
122+
| `--sort` | Sort field: `name`, `date`, `size` | `date` |
123+
| `--order`, `-o` | Sort order: `asc`, `desc` | `desc` |
124+
| `--json` | Output as JSON | `false` |
125+
126+
### Examples
127+
128+
```bash
129+
# List all log files
130+
b2c logs list
131+
132+
# List only error logs
133+
b2c logs list --filter error --filter customerror
134+
135+
# Sort by size
136+
b2c logs list --sort size --order desc
137+
138+
# JSON output
139+
b2c logs list --json
140+
```
141+
142+
### Output
143+
144+
```
145+
Name Type Size Modified
146+
────────────────────────────────────────────────────────────────────────────────
147+
error-blade0-1-appserver-20260125.log error 245.2 KB 1/25/2026, 10:30 AM
148+
customerror-blade0-1-appserver-20260125.log customerror 128.5 KB 1/25/2026, 10:28 AM
149+
debug-blade0-1-appserver-20260125.log debug 1.2 MB 1/25/2026, 10:25 AM
150+
```
151+
152+
---
153+
154+
## b2c logs tail
155+
156+
Tail log files in real-time. This is an interactive command that continuously monitors logs until stopped with Ctrl+C.
157+
158+
### Usage
159+
160+
```bash
161+
b2c logs tail
162+
```
163+
164+
### Flags
165+
166+
| Flag | Description | Default |
167+
|------|-------------|---------|
168+
| `--filter`, `-f` | Log prefixes to filter (can specify multiple) | `error`, `customerror` |
169+
| `--interval` | Polling interval in milliseconds | `3000` |
170+
| `--last`, `-l` | Show last N entries per file on startup (0 to skip) | `1` |
171+
| `--level` | Filter by log level (can specify multiple): ERROR, WARN, INFO, DEBUG, FATAL, TRACE | - |
172+
| `--search`, `-g` | Filter entries containing this text (case-insensitive) | - |
173+
| `--cartridge-path` | Override cartridge path for path normalization | Auto-discovered |
174+
| `--no-normalize` | Disable automatic path normalization | `false` |
175+
| `--no-color` | Disable colored output | `false` |
176+
| `--json` | Output as NDJSON (newline-delimited JSON) | `false` |
177+
178+
### Examples
179+
180+
```bash
181+
# Tail error and customerror logs (default)
182+
b2c logs tail
183+
184+
# Tail specific log types
185+
b2c logs tail --filter debug --filter error --filter warn
186+
187+
# Faster polling (1 second)
188+
b2c logs tail --interval 1000
189+
190+
# Start without showing historical entries
191+
b2c logs tail --last 0
192+
193+
# Show last 5 entries per file on startup
194+
b2c logs tail --last 5
195+
196+
# Tail only ERROR and FATAL entries
197+
b2c logs tail --level ERROR --level FATAL
198+
199+
# Tail with text search
200+
b2c logs tail --search "PaymentProcessor"
201+
202+
# Combined filtering
203+
b2c logs tail --filter customerror --level ERROR --search "OrderMgr"
204+
205+
# NDJSON output for streaming parsers
206+
b2c logs tail --json
207+
```
208+
209+
### Notes
210+
211+
- This is an **interactive command** that runs until interrupted with Ctrl+C
212+
- The command discovers and monitors all matching log files, including newly created files during rotation
213+
- JSON mode outputs NDJSON (one JSON object per line) suitable for streaming parsers
214+
- For non-interactive log retrieval, use `b2c logs get` instead
215+
216+
---
217+
218+
## Log File Types
219+
220+
B2C Commerce instances generate various log files:
221+
222+
### Custom Logs (Script-Generated)
223+
224+
| Type | Generated By | Default State |
225+
|------|--------------|---------------|
226+
| `customdebug` | `Logger.debug()` | Disabled |
227+
| `custominfo` | `Logger.info()` | Disabled |
228+
| `customwarn` | `Logger.warn()` | Always enabled |
229+
| `customerror` | `Logger.error()` | Always enabled |
230+
| `customfatal` | `log.fatal()` | Always enabled |
231+
232+
### System Logs
233+
234+
| Type | Description |
235+
|------|-------------|
236+
| `error` | System errors in scripts, templates, platform |
237+
| `warn` | Lock status, slot warnings, servlet warnings |
238+
| `info` | System information |
239+
| `debug` | Debug information (when enabled) |
240+
| `fatal` | Critical system failures |
241+
| `api` | API problems and violations |
242+
| `deprecation` | Usage of deprecated APIs |
243+
| `jobs` | Job status information |
244+
| `quota` | Quota warnings and limit violations |
245+
246+
---
247+
248+
## Downloading Full Log Files
249+
250+
To download the complete log file for deeper investigation, use `b2c webdav get` with the filename from the log entry (shown in brackets in human output, or the `file` field in JSON output):
251+
252+
```bash
253+
b2c webdav get error-odspod-0-appserver-20260126.log --root=logs -o -
254+
```
255+
256+
See [WebDAV Commands](/cli/webdav#reading-log-files) for more details on log file access.
257+
258+
---
259+
260+
## See Also
261+
262+
- [WebDAV Commands](/cli/webdav) - Direct file access for downloading full log files
263+
- [Configuration](/guide/configuration) - Setting up instance credentials

0 commit comments

Comments
 (0)