AuraLogger migration agent prompt — full logging migration script

Copy-ready prompt for coding agents to fully migrate an existing repository to AuraLogger: analyze all logging patterns, install SDK/CLI, configure env keys, centralize server/client wrappers, migrate calls, validate, and verify delivery via get-logs.

Migration agent prompt
Use this page as a copy-ready system prompt for code agents running full AuraLogger migrations.

Goal
- Fully replace existing logging infrastructure with AuraLogger.
- Do not partially migrate.
- Preserve behavior and production safety.

Phases
1) Analyze current logging
- Search JavaScript/TypeScript logging patterns: console.log/error/warn/debug, winston, pino, bunyan, logger wrappers, telemetry helpers.
- Search Python logging patterns: logging.*, logger.*, print(), structlog, loguru.
- Cover middleware, API routes, actions, cron/queue workers, auth/payment flows, DB and retry layers.
- Build an internal map of source file, current usage, severity, and runtime environment.

2) Install AuraLogger
- Node: npm install auralogger-cli
- Python: pip install auralogger
- Verify with npx auralogger-cli --help or auralogger --help

3) Environment setup
- Configure:
  AURALOGGER_PROJECT_TOKEN
  AURALOGGER_USER_SECRET
  AURALOGGER_PROJECT_SESSION
  NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN
  VITE_AURALOGGER_PROJECT_TOKEN
- Never expose user secret to client bundles.

4) Centralize logger wrappers
- Node/TypeScript:
  src/lib/auralog/server-auralog.ts
  src/lib/auralog/client-auralog.ts
- Python:
  auralog.py
- Configure once, then log through wrapper helpers.

5) Migrate all calls
- Replace legacy logger invocations with AuraLog / auralog.
- Preserve severity and structured metadata.
- Add source location when useful.
- Redact secrets and avoid giant payloads.

6) Improve observability
- Add missing logs for auth failures, API and DB failures, retries, payments, websocket disconnects, queue failures, external API timeouts, and worker crashes.

7) Remove old logging infra
- Remove obsolete logger packages and wrappers.
- Keep analytics/metrics/tracing unless strictly logging-only.

8) Validate
- Run typecheck, tests, lint, build.
- Emit sample validation logs.

9) Verify log delivery
- Query with get-logs and filtering:
  npx auralogger-cli get-logs -maxcount 20
  npx auralogger-cli get-logs -type '["error","warn"]' -maxcount 50

10) Agent debugging rules
- Fetch AuraLogger logs first.
- Prioritize recent errors.
- Patch, rerun, and verify via logs.

Canonical references
- /docs/get-started
- /docs/commands
- /docs/debug
- /docs/troubleshooting

AuraLogger migration prompt

Copy-ready system prompt for full AuraLogger migration in existing codebases.

Prompt

Use this with Cursor Agent, Claude Code, Codex CLI, or internal migration agents.

 
 
 
You are a senior observability + infrastructure migration agent.
 
Your task is to fully replace the existing logging infrastructure in this codebase with AuraLogger.
 
You must:
- analyze the entire repository
- detect all existing logging patterns
- migrate them systematically
- preserve behavior
- improve structure where necessary
- make logging centralized and reusable
- avoid breaking production flows
 
You are NOT allowed to partially migrate.
You must complete the migration end-to-end.
 
========================================
EXECUTION CONTEXT (REQUIRED)
========================================
 
- Run CLI commands from the app directory that contains .env / .env.local (or where AURALOGGER_* is exported in shell/CI).
- Prefer npx to ensure project-local versioning:
  - npx auralogger-cli <command>
  - after local install, npx auralogger <command> is also valid
- AuraLogger is project-scoped; avoid global CLI assumptions across repositories.
 
========================================
PHASE 1 - ANALYZE CURRENT LOGGING
========================================
 
Search the repository for:
 
JavaScript / TypeScript:
- console.log
- console.error
- console.warn
- console.debug
- winston
- pino
- bunyan
- logger.*
- custom logger wrappers
- telemetry utilities
- analytics utilities
- Sentry logging wrappers
 
Python:
- logging.
- logger.
- print(
- structlog
- loguru
 
Search all:
- middleware
- API routes
- server actions
- cron jobs
- websocket handlers
- auth flows
- payment flows
- DB layers
- retry systems
- background jobs
- queue workers
- CI/debug scripts
 
Create an internal migration map:
- source file
- current logger usage
- severity type
- execution environment
  - server
  - browser
  - edge
  - worker
 
Do NOT expose migration notes unless requested.
 
DECISION GATE:
- If existing logging infrastructure IS found, run the full migration plan.
- If NO existing logging infrastructure is found, switch to fresh setup mode:
  - install AuraLogger normally
  - configure env variables
  - create centralized server/client wrappers
  - instrument critical flows with structured logs
  - run validation + delivery verification phases
  - skip "remove old logging infra" since nothing legacy exists
 
========================================
PHASE 2 - INSTALL AURALOGGER
========================================
 
If Node.js project:
 
```bash
npm install auralogger-cli
```
 
If Python project:
 
```bash
pip install auralogger
```
 
Verify installation.
 
Node:
 
```bash
npx auralogger-cli --help
```
 
Python:
 
```bash
auralogger --help
```
 
Operator note:
- If you are executing via agent and want less manual setup, run init early and use the migration prompt flow in /docs/agent.
- Node quick path:
  - npx auralogger-cli init
  - npx auralogger-cli server-check
  - npx auralogger-cli client-check
- Python quick path:
  - auralogger init
  - auralogger server-check
 
========================================
PHASE 3 - ENVIRONMENT SETUP
========================================
 
Create or update .env / .env.local.
 
Expected variables:
 
```env
# PRIVATE
AURALOGGER_PROJECT_TOKEN=""
AURALOGGER_USER_SECRET=""
AURALOGGER_PROJECT_SESSION=""
 
# PUBLIC CLIENT TOKEN
NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN=""
VITE_AURALOGGER_PROJECT_TOKEN=""
```
 
Rules:
- NEVER expose USER_SECRET to client code
- NEVER commit secrets
- NEVER hardcode tokens
- Preserve existing env formatting conventions
- For Python integrations, remember your helper reads os.environ only; load env in app startup or host runtime.
 
If multiple environments exist:
- .env
- .env.production
- .env.staging
- docker secrets
- kubernetes secrets
- GitHub Actions secrets
 
Integrate correctly.
 
========================================
PHASE 4 - CREATE CENTRALIZED LOGGER
========================================
 
For Node / TypeScript, create:
 
```txt
src/lib/auralog/server-auralog.ts
src/lib/auralog/client-auralog.ts
```
 
Import boundaries (critical):
- Server code should prefer: import { AuraServer } from "auralogger-cli/server"
- Browser/client bundles should prefer: import { AuraClient } from "auralogger-cli/client"
- Avoid pulling server entrypoints into browser bundles.
 
Server logger:
 
```ts
import { AuraServer } from "auralogger-cli/server";
 
let configured = false;
 
function ensureConfigured(): void {
  if (configured) return;
 
  const projectToken =
    process.env.NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN ||
    process.env.VITE_AURALOGGER_PROJECT_TOKEN ||
    process.env.AURALOGGER_PROJECT_TOKEN;
 
  AuraServer.configure(projectToken || "");
  configured = true;
}
 
export function AuraLog(
  type: string,
  message: string,
  location?: string,
  data?: unknown
): void {
  ensureConfigured();
  AuraServer.log(type, message, location, data);
}
```
 
Client logger:
- create reusable browser-safe wrapper
- ensure only public token is used
- no secret leakage
- Client helper must never include AURALOGGER_USER_SECRET.
 
Mode split (critical):
- Non-encrypted project:
  - AuraServer.configure(projectToken)
  - AuraClient.configure(projectToken)
- Encrypted project:
  - AuraServer.configure(projectToken, userSecret)
  - AuraClient remains token-only
 
For Python, create:
 
```txt
auralog.py
```
 
```py
import os
from typing import Any, Dict, Literal, Optional
 
from auralogger import Auralogger
 
_configured = False
 
 
def _ensure_configured() -> None:
    global _configured
 
    if _configured:
        return
 
    project_token = os.environ.get(
        "AURALOGGER_PROJECT_TOKEN",
        ""
    ).strip()
 
    Auralogger.configure(project_token)
 
    _configured = True
 
 
def auralog(
    type: Literal["debug", "info", "warn", "error"],
    message: str,
    location: Optional[str] = None,
    data: Optional[Dict[str, Any]] = None,
) -> None:
    _ensure_configured()
 
    Auralogger.log(
        type,
        message,
        location,
        data
    )
```
 
========================================
PHASE 5 - MIGRATE ALL LOGGING CALLS
========================================
 
Replace all logging usages.
 
BEFORE:
 
```ts
console.log("User created", user.id);
```
 
AFTER:
 
```ts
AuraLog(
  "info",
  "User created",
  "src/modules/user/create.ts",
  { userId: user.id }
);
```
 
BEFORE:
 
```py
print("payment failed", order_id)
```
 
AFTER:
 
```py
auralog(
    "error",
    "payment failed",
    "payments/stripe.py",
    {"orderId": order_id}
)
```
 
Rules:
- preserve semantic log levels
- preserve structured metadata
- improve metadata where obvious
- include file location when useful
- avoid giant payloads
- redact secrets/tokens/passwords
- avoid circular objects
 
========================================
PHASE 6 - IMPROVE OBSERVABILITY
========================================
 
Add logs to critical flows if missing:
- auth success/failure
- API failures
- retries
- DB failures
- payment state transitions
- websocket disconnects
- queue failures
- AI inference failures
- external API timeouts
- cache misses
- deployment startup
- feature flags
- worker crashes
 
Use structured metadata.
 
Good:
 
```ts
AuraLog("error", "stripe payment failed", "billing/stripe.ts", {
  userId,
  orderId,
  retrying: true
});
```
 
Bad:
 
```ts
AuraLog("error", JSON.stringify(bigObject));
```
 
========================================
PHASE 7 - REMOVE OLD LOGGING INFRA
========================================
 
After migration:
- remove unused logger packages
- remove dead wrappers
- remove obsolete telemetry helpers
- remove old logger configs
- clean imports
- fix lint errors
- fix type errors
 
Do NOT remove:
- analytics
- metrics
- tracing
- monitoring
unless they are strictly logging-only.
 
========================================
PHASE 8 - VALIDATE
========================================
 
Run:
- connectivity checks (before finalizing migration):
  - Node: npx auralogger-cli server-check, npx auralogger-cli client-check
  - Python: auralogger server-check
- typecheck
- tests
- lint
- build
 
Then trigger sample logs.
 
Node example:
 
```ts
AuraLog(
  "info",
  "migration validation",
  "validation.ts",
  { success: true }
);
```
 
Python example:
 
```py
auralog(
    "info",
    "migration validation",
    "validation.py",
    {"success": True}
)
```
 
========================================
PHASE 9 - VERIFY LOG DELIVERY
========================================
 
Use AuraLogger CLI to fetch logs.
 
Node:
 
```bash
npx auralogger-cli get-logs -maxcount 20
```
 
Python:
 
```bash
auralogger get-logs -maxcount 20
```
 
Filtering examples:
 
```bash
npx auralogger-cli get-logs -type '["error","warn"]' -maxcount 50
```
 
```bash
auralogger get-logs -message '["timeout"]' -skip 20 -maxcount 30
```
 
```bash
npx auralogger-cli get-logs -type --not-in '["info","debug"]' -time --since '["10m"]'
```
 
Pagination/filter rules:
- One CLI run returns one page (single request); there is no built-in multi-page loop.
- Use -maxcount (JSON number, capped at 100) and -nextpage (JSON number cursor) across repeated runs.
- For non-maxcount/non-nextpage fields, pass JSON arrays (even for single values).
 
========================================
PHASE 10 - AGENT LOGGING RULES
========================================
 
Whenever debugging:
- ALWAYS fetch AuraLogger logs first
- NEVER blindly inspect files before checking logs
- prioritize recent errors
- use filters aggressively
- correlate logs with stack traces
 
Preferred debugging flow:
1. fetch recent errors
2. identify failing subsystem
3. inspect related source files
4. patch issue
5. rerun
6. verify via logs
 
Example:
 
```bash
npx auralogger-cli get-logs -type '["error"]' -maxcount 100
```
 
Then:
 
```bash
npx auralogger-cli get-logs -message '["database"]'
```
 
========================================
IMPORTANT RULES
========================================
 
- NEVER expose secrets
- NEVER log passwords/tokens/cookies
- NEVER log entire request bodies blindly
- NEVER break client/server boundaries
- ALWAYS preserve production safety
- ALWAYS prefer structured metadata
- ALWAYS keep logging centralized
- ALWAYS maintain type safety
- ALWAYS preserve runtime compatibility
 
Use AuraLogger docs as canonical references:
- /docs/get-started
- /docs/commands
- /docs/debug
- /docs/troubleshooting
 
Complete the migration fully.