| name | x-ipe-tool-tracing-instrumentation |
| description | Add @x_ipe_tracing decorators to Python functions. Analyzes code, suggests levels (INFO/DEBUG), detects sensitive params for redaction, and applies decorators in batch. Triggers on "add tracing to", "instrument for tracing", "trace functions in". |
Tool: Tracing Instrumentation
Purpose
AI Agents follow this skill to instrument Python code with @x_ipe_tracing decorators to:
- Analyze target file(s) for traceable functions using AST
- Assign appropriate tracing levels (INFO/DEBUG) based on context
- Detect sensitive parameters and configure redaction
- Present proposals for human review before applying changes
- Apply decorators and imports in batch after approval
Important Notes
BLOCKING: Never apply decorators without presenting a proposal and receiving human approval first.
CRITICAL: Always check parameters against the sensitive-param patterns list. Sensitive data leaking into traces is a security risk.
CRITICAL: Add @x_ipe_tracing as the outermost decorator when other decorators exist.
About
This tool automates adding @x_ipe_tracing decorators to Python functions. It uses Python AST parsing to discover functions, classify them by tracing level, detect parameters that need redaction, and apply changes surgically.
Key Concepts:
- Tracing Level - INFO for public/API functions, DEBUG for internal/utility functions
- Redaction - Automatic detection of sensitive parameter names (passwords, tokens, keys) to add
redact=[...] to the decorator
- Proposal-first - All changes are shown as a markdown table for human review before any file modification
When to Use
triggers:
- "add tracing to {file/module}"
- "instrument {file/module} for tracing"
- "add @x_ipe_tracing to {file}"
- "trace all functions in {path}"
- "add tracing decorators to {path}"
not_for:
- "Configuring tracing runtime settings (use tracing dashboard)"
- "Viewing or querying existing traces (use tracing API)"
Input Parameters
input:
target: "string (required) - File path or directory to instrument"
options:
level: "string (default: 'auto') - Force level: INFO, DEBUG, or auto"
include_private: "bool (default: false) - Include _prefixed functions"
dry_run: "bool (default: false) - Only show proposed changes, do not apply"
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Target path exists</name>
<verification>Verify file (.py) or directory exists at specified path</verification>
</checkpoint>
<checkpoint required="true">
<name>Tracing module available</name>
<verification>Confirm x_ipe.tracing module exists in the project</verification>
</checkpoint>
</definition_of_ready>
Operations
Operation: Analyze and Propose
When: Human requests tracing instrumentation for a target path.
<operation name="analyze_and_propose">
<action>
1. Validate target path exists (file must be .py; directory: find .py files recursively)
2. Exclude: __pycache__/, .venv/, venv/, env/, test_*.py, *_test.py, conftest.py
3. Report scope: "Found X Python files in {target}"
4. For each file, parse with Python AST to extract FunctionDef and AsyncFunctionDef nodes
5. For each function:
a. Skip if already has @x_ipe_tracing decorator
b. Skip dunder methods (__init__, __str__, etc.)
c. Skip _private functions unless include_private=true
d. Extract: name, parameters (with type hints), line number, is_async, existing decorators
6. Assign tracing level per priority rules:
P1: Explicit level param != "auto" -> use that level
P2: File in routes/ or api/ directory -> INFO
P3: Class ends with Service, Handler, Controller -> INFO
P4: Public function (no _ prefix) -> INFO
P5: File in utils/, helpers/, internal/ -> DEBUG
P6: Protected function (_prefix) -> DEBUG
P7: Default fallback -> INFO
7. Check each parameter name against sensitive patterns (see references/edge-cases.md)
If match: add to redact=["param_name"] list
8. Present proposal as markdown table with Function, Line, Level, Redact, Action columns
9. Show summary (files analyzed, to instrument, already traced, excluded)
10. Ask: "Proceed?" with options: Yes / Exclude: func1,func2 / No
</action>
<constraints>
- BLOCKING: Do not modify any files during this operation
- Always show proposal even in dry_run mode
</constraints>
<output>Markdown proposal table with per-function instrumentation plan</output>
</operation>
Operation: Apply Decorators
When: Human approves the proposal (replies "Yes" or excludes specific functions).
<operation name="apply_decorators">
<action>
1. Remove any functions the human excluded from the approved list
2. For each file with approved functions:
a. Check for existing import: from x_ipe.tracing import x_ipe_tracing
b. If missing, add import after other imports (before first function/class)
3. For each approved function, add decorator:
- No redaction: @x_ipe_tracing(level="{LEVEL}")
- With redaction: @x_ipe_tracing(level="{LEVEL}", redact=["{param1}", "{param2}"])
4. Place @x_ipe_tracing as outermost decorator (before any existing decorators)
5. Async functions use the same decorator syntax
6. Report results: files modified, functions instrumented, imports added, redactions applied
7. Suggest next steps: run tests, start tracing, check trace logs
</action>
<constraints>
- BLOCKING: Requires human approval from analyze_and_propose
- Preserve existing decorator order (add tracing above them)
- Skip if dry_run=true (report "No changes made, dry run only")
</constraints>
<output>Summary of applied changes with file-level breakdown</output>
</operation>
Output Result
operation_output:
success: true | false
result:
files_modified: 0
functions_instrumented: 0
imports_added: 0
functions_with_redaction: 0
functions_skipped_already_traced: 0
functions_excluded: 0
errors: []
next_steps:
- "Run tests: pytest tests/"
- "Start tracing: Use Tracing Dashboard or API"
- "View traces: Check instance/traces/ for logs"
Definition of Done
<definition_of_done>
<checkpoint required="true">
<name>Target validated</name>
<verification>Target path confirmed to exist with .py files</verification>
</checkpoint>
<checkpoint required="true">
<name>AST analysis complete</name>
<verification>All files parsed, functions classified by level</verification>
</checkpoint>
<checkpoint required="true">
<name>Sensitive params detected</name>
<verification>All parameters checked against sensitive patterns</verification>
</checkpoint>
<checkpoint required="true">
<name>Proposal shown and approved</name>
<verification>Human reviewed and approved the proposal</verification>
</checkpoint>
Decorators applied correctly
All approved functions have @x_ipe_tracing with correct level and redact params
Imports added
Files with new decorators have the tracing import
Results reported
Summary of changes provided to human
Error Handling
| Error | Cause | Resolution |
|---|
| Target path not found | Invalid file/directory path | Report error, ask human for correct path |
| Not a Python file | Target file lacks .py extension | Report error, skip file |
| AST parse failure | Syntax error in Python file | Report "Error parsing {filepath}: {error}", skip file, continue with others |
| No traceable functions | File has no eligible functions | Report "No traceable functions found in {filepath}" |
| Human declines proposal | Replied "No" | Cancel operation, no files modified |
Templates
| File | Purpose |
|---|
references/examples.md | Detailed usage examples (single file, batch, auth, exclusions) |
references/edge-cases.md | Edge cases, anti-patterns, and sensitive parameter patterns |
Examples
See references/examples.md for usage examples including:
- Single file instrumentation
- Auth service with sensitive parameter redaction
- Module/directory batch processing
- Excluding specific functions from instrumentation
- Dry run mode
