Profiling
The ProfilingController provides continuous profiling capabilities for platform services. Profiling captures CPU, memory, and I/O profiles at the application level, enabling developers to identify performance bottlenecks and memory leaks without impacting production traffic.
Start a Profile
Endpoint: POST /api/v1/observability/profiling/start
curl -X POST http://localhost:8088/api/v1/observability/profiling/start \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-H "X-Tenant-ID: 550e8400" \
-d '{
"service": "ai-service",
"profileType": "cpu",
"durationSeconds": 60,
"sampleRate": 100
}'ProfileRequest Structure
| Field | Type | Description |
|---|---|---|
service | String | Target service name |
profileType | String | cpu, memory, alloc, block, mutex, goroutine |
durationSeconds | int | Profile duration in seconds |
sampleRate | int | Sampling rate (samples per second) |
Profile Types
| Type | Description | Best For |
|---|---|---|
cpu | CPU time spent in each function | Identifying slow code paths |
memory | Current memory allocation by function | Finding memory-heavy operations |
alloc | Cumulative memory allocations | Detecting allocation-heavy code |
block | Goroutine blocking events | Finding lock contention |
mutex | Mutex contention | Identifying synchronization bottlenecks |
goroutine | Active goroutine stacks | Detecting goroutine leaks |
Get Profile Results
Endpoint: GET /api/v1/observability/profiling/:profileId
ProfileResult Structure
| Field | Type | Description |
|---|---|---|
id | String | Profile identifier |
service | String | Profiled service |
profileType | String | Type of profile |
status | String | running, completed, failed |
startedAt | Instant | Profile start time |
completedAt | Instant | Profile completion time |
durationSeconds | int | Actual profile duration |
sampleCount | int | Number of samples collected |
topFunctions | List | Top functions by resource usage |
flameGraphUrl | String | URL to the flame graph visualization |
Compare Profiles
Endpoint: GET /api/v1/observability/profiling/compare
Compares two profiles to identify performance regressions or improvements.
| Parameter | Type | Description |
|---|---|---|
baseProfileId | String | Baseline profile ID |
comparisonProfileId | String | Comparison profile ID |
ProfileComparison Structure
| Field | Type | Description |
|---|---|---|
baseProfile | String | Base profile identifier |
comparisonProfile | String | Comparison profile identifier |
improvements | List | Functions that improved |
regressions | List | Functions that regressed |
unchanged | int | Number of unchanged functions |
overallDelta | double | Overall performance delta percentage |
Continuous Profiling
Endpoint: POST /api/v1/observability/profiling/continuous
Enables continuous profiling for a service with low-overhead sampling.
ContinuousProfile Structure
| Field | Type | Description |
|---|---|---|
service | String | Target service |
profileTypes | List | Types to profile continuously |
sampleRate | int | Sampling rate |
retentionDays | int | How long to retain profiles |
enabled | boolean | Whether continuous profiling is active |
Profile History
Endpoint: GET /api/v1/observability/profiling/history
Returns historical profiles for a service, enabling trend analysis of performance over time.