# Code Instrumentation Generator

> Automatically instruments source code to collect runtime information such as function calls, branch decisions, variable values, and execution traces while preserving original program semantics. Use when users need to: (1) Add logging or tracing to code for debugging, (2) Collect runtime execution data for analysis, (3) Monitor function calls and control flow, (4) Track variable values during exec…

- **Type:** Skill
- **Install:** `agentstack add skill-arabelatso-skills-4-se-code-instrumentation-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ArabelaTso](https://agentstack.voostack.com/s/arabelatso)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ArabelaTso](https://github.com/ArabelaTso)
- **Source:** https://github.com/ArabelaTso/Skills-4-SE/tree/main/skills/code-instrumentation-generator
- **Website:** https://ArabelaTso.github.io/Skills-4-SE/

## Install

```sh
agentstack add skill-arabelatso-skills-4-se-code-instrumentation-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Code Instrumentation Generator

Automatically instrument source code to collect runtime information while preserving program semantics.

## Workflow

Follow these steps to instrument code:

### 1. Analyze the Source Code

Understand the code structure and identify instrumentation points:

- **Language detection**: Identify the programming language
- **Code structure**: Parse functions, classes, branches, loops
- **Entry/exit points**: Locate function boundaries
- **Control flow**: Identify branches (if/else, switch, loops)
- **Variable scope**: Understand variable declarations and usage

### 2. Determine Instrumentation Strategy

Choose appropriate instrumentation based on requirements:

**Instrumentation levels:**
- **Function-level**: Entry/exit of functions with parameters and return values
- **Branch-level**: Execution of conditional branches (if/else, switch cases)
- **Statement-level**: Individual statement execution
- **Variable-level**: Variable assignments and value changes

**Configuration options:**
- Enable/disable specific instrumentation types
- Filter by function names or file patterns
- Set verbosity level
- Choose output format (logs, JSON, CSV)

### 3. Insert Instrumentation Code

Add instrumentation hooks at identified points:

**Function instrumentation:**
- Insert entry hook at function start
- Capture function name, parameters, timestamp
- Insert exit hook before returns
- Capture return value, execution time

**Branch instrumentation:**
- Insert hooks at branch conditions
- Record which branch was taken
- Track branch coverage

**Variable instrumentation:**
- Insert hooks after variable assignments
- Capture variable name and value
- Track value changes over time

### 4. Ensure Semantic Preservation

Verify that instrumentation doesn't change program behavior:

- **No side effects**: Instrumentation code doesn't modify program state
- **Exception safety**: Instrumentation handles exceptions properly
- **Performance**: Minimal overhead added
- **Thread safety**: Instrumentation is safe in concurrent code

### 5. Generate Output

Provide instrumented code and documentation:

- **Instrumented source code**: Modified code with instrumentation
- **Probe description**: Documentation of inserted instrumentation points
- **Configuration file**: Settings to enable/disable instrumentation
- **Usage instructions**: How to run and collect data

## Language-Specific Patterns

### Python

```python
# Original code
def calculate_sum(a, b):
    result = a + b
    return result

# Instrumented code
import logging
logging.basicConfig(level=logging.INFO)

def calculate_sum(a, b):
    # Function entry instrumentation
    logging.info(f"ENTER calculate_sum(a={a}, b={b})")

    result = a + b
    # Variable instrumentation
    logging.info(f"VAR result={result}")

    # Function exit instrumentation
    logging.info(f"EXIT calculate_sum() -> {result}")
    return result
```

### Java

```java
// Original code
public int calculateSum(int a, int b) {
    int result = a + b;
    return result;
}

// Instrumented code
public int calculateSum(int a, int b) {
    // Function entry instrumentation
    System.out.println("ENTER calculateSum(a=" + a + ", b=" + b + ")");

    int result = a + b;
    // Variable instrumentation
    System.out.println("VAR result=" + result);

    // Function exit instrumentation
    System.out.println("EXIT calculateSum() -> " + result);
    return result;
}
```

### JavaScript

```javascript
// Original code
function calculateSum(a, b) {
    const result = a + b;
    return result;
}

// Instrumented code
function calculateSum(a, b) {
    // Function entry instrumentation
    console.log(`ENTER calculateSum(a=${a}, b=${b})`);

    const result = a + b;
    // Variable instrumentation
    console.log(`VAR result=${result}`);

    // Function exit instrumentation
    console.log(`EXIT calculateSum() -> ${result}`);
    return result;
}
```

### C/C++

```c
// Original code
int calculate_sum(int a, int b) {
    int result = a + b;
    return result;
}

// Instrumented code
#include 

int calculate_sum(int a, int b) {
    // Function entry instrumentation
    printf("ENTER calculate_sum(a=%d, b=%d)\n", a, b);

    int result = a + b;
    // Variable instrumentation
    printf("VAR result=%d\n", result);

    // Function exit instrumentation
    printf("EXIT calculate_sum() -> %d\n", result);
    return result;
}
```

## Branch Instrumentation Example

```python
# Original code
def check_value(x):
    if x > 0:
        return "positive"
    else:
        return "non-positive"

# Instrumented code
def check_value(x):
    logging.info(f"ENTER check_value(x={x})")

    # Branch instrumentation
    if x > 0:
        logging.info("BRANCH if(x > 0) -> TRUE")
        result = "positive"
    else:
        logging.info("BRANCH if(x > 0) -> FALSE")
        result = "non-positive"

    logging.info(f"EXIT check_value() -> {result}")
    return result
```

## Configuration-Based Instrumentation

Generate a configuration file to control instrumentation:

```python
# instrumentation_config.py
INSTRUMENTATION_ENABLED = True
INSTRUMENT_FUNCTIONS = True
INSTRUMENT_BRANCHES = True
INSTRUMENT_VARIABLES = False
LOG_LEVEL = "INFO"
OUTPUT_FORMAT = "text"  # or "json", "csv"

# Instrumented code with configuration
import instrumentation_config as config

def calculate_sum(a, b):
    if config.INSTRUMENT_FUNCTIONS:
        logging.info(f"ENTER calculate_sum(a={a}, b={b})")

    result = a + b

    if config.INSTRUMENT_VARIABLES:
        logging.info(f"VAR result={result}")

    if config.INSTRUMENT_FUNCTIONS:
        logging.info(f"EXIT calculate_sum() -> {result}")

    return result
```

## Output Format

### Probe Description Document

```markdown
## Instrumentation Report

**File**: calculator.py
**Instrumentation Date**: 2024-02-17
**Configuration**: Function-level + Branch-level

### Instrumented Functions

1. **calculate_sum(a, b)**
   - Entry probe: Line 3
   - Exit probe: Line 8
   - Captures: Parameters (a, b), return value

2. **check_value(x)**
   - Entry probe: Line 11
   - Branch probe: Line 14 (if x > 0)
   - Exit probe: Line 19
   - Captures: Parameter (x), branch decision, return value

### Instrumentation Statistics
- Total functions instrumented: 2
- Total branches instrumented: 1
- Total variables instrumented: 0
- Estimated overhead:  {result} [time={elapsed:.6f}s]")
    return result
```

### JSON Output Format

```python
import json
import time

def calculate_sum(a, b):
    entry_event = {
        "type": "function_entry",
        "function": "calculate_sum",
        "params": {"a": a, "b": b},
        "timestamp": time.time()
    }
    print(json.dumps(entry_event))

    result = a + b

    exit_event = {
        "type": "function_exit",
        "function": "calculate_sum",
        "return_value": result,
        "timestamp": time.time()
    }
    print(json.dumps(exit_event))

    return result
```

## Constraints

- **Preserve semantics**: Never change program behavior
- **Minimal overhead**: Keep instrumentation lightweight
- **No side effects**: Instrumentation shouldn't modify program state
- **Exception safety**: Handle errors gracefully
- **Configurable**: Allow enabling/disabling instrumentation

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ArabelaTso](https://github.com/ArabelaTso)
- **Source:** [ArabelaTso/Skills-4-SE](https://github.com/ArabelaTso/Skills-4-SE)
- **License:** Apache-2.0
- **Homepage:** https://ArabelaTso.github.io/Skills-4-SE/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-arabelatso-skills-4-se-code-instrumentation-generator
- Seller: https://agentstack.voostack.com/s/arabelatso
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.