home / skills / yelmuratoff / agent_sync / logging

logging skill

safe

This skill helps you implement structured, non-PII logging with ISpect.logger to monitor app flow, capture exceptions, and improve observability.

npx playbooks add skill yelmuratoff/agent_sync --skill logging

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: logging
description: When logging or handling exceptions using `ISpect.logger` (no print/debugPrint, no PII).
---

# Logging (ISpect)

## When to use

- Logging operational information (startup, navigation milestones, feature boundaries).
- Logging warnings (non-fatal but important issues).
- Handling and reporting exceptions at async boundaries (BLoC/repository/datasource).

## Steps

### 1) Use ISpect for all logging

```dart
ISpect.logger.info('Orders screen opened');
ISpect.logger.warning('Slow response from orders API');
ISpect.logger.debug('Orders refreshed (count: $count)');
```

Do not use `print`, `debugPrint`, or `log`.

### 2) Use ISpect.logger.handle for caught exceptions

```dart
try {
  await repository.getOrders();
} catch (e, st) {
  ISpect.logger.handle(
    exception: e,
    stackTrace: st,
    message: 'Failed to load orders',
  );
  rethrow;
}
```

### 3) Avoid PII and secrets

Never log:

- tokens, credentials, session identifiers
- emails/phones, names, addresses, IDs
- raw request/response payloads that may include user data

### 4) Attach structured context when safe

If ISpect is configured for structured logging, attach small non-sensitive context:

```dart
ISpect.logger.log(
  'Orders refresh completed',
  key: 'orders_refresh',
  data: {'count': count, 'source': source},
);
```

Overview

This skill standardizes logging and exception handling using ISpect.logger for AI agent projects. It enforces structured, non-sensitive logs and replaces ad-hoc print/debugPrint calls. The result is consistent operational telemetry and safer error reporting across async boundaries.

How this skill works

The skill directs developers to use ISpect.logger methods (info, warning, debug, log) for all runtime messages and ISpect.logger.handle for caught exceptions. It forbids print/debugPrint/log for application logging and mandates avoiding PII and secrets. When configured, the skill recommends attaching small, non-sensitive structured context to events.

When to use it

Record startup events, navigation milestones, and feature boundaries.
Emit warnings for non-fatal but actionable conditions (performance, retries).
Report and enrich exceptions caught at async boundaries (BLoC, repository, datasource).
Log successful operational outcomes (refreshes, sync completions) with counts.
Attach small context when structured logging is enabled and safe.

Best practices

Always use ISpect.logger.* methods instead of print, debugPrint, or raw log calls.
Use ISpect.logger.handle(exception:..., stackTrace:..., message:...) for caught errors and then rethrow if appropriate.
Never log PII or secrets: tokens, credentials, emails, phones, addresses, IDs, or raw payloads containing user data.
Keep structured context minimal and non-sensitive (e.g., counts, feature source, non-identifying IDs).
Prefer clear, actionable messages that aid debugging and monitoring without exposing sensitive details.

Example use cases

Log 'Orders screen opened' with ISpect.logger.info when the UI appears.
Use ISpect.logger.warning for slow API responses and potential degradation.
Handle repository exceptions with ISpect.logger.handle to capture stack traces and a short message.
Record 'Orders refresh completed' with a count and source in data when safe.
Avoid logging raw network responses; extract only non-sensitive metrics (size, status).

FAQ

Can I log request/response payloads for debugging?

No—avoid raw payloads that may include PII. Extract and log only non-sensitive metrics or anonymized fields.

When should I use ISpect.logger.handle vs info/warning?

Use handle for caught exceptions where you want stack traces and error context. Use info/warning for operational or non-exceptional conditions.