Release Notes

Breaking Changes

• Labels Package Redesign (9699ed3, a69e19d):
  • Moved from io.pyroscope.labels to io.pyroscope.labels.v2 package
  • Added nullability annotations (@NotNull) to all public methods and parameters to improve type safety and prevent null pointer exceptions
  • Eliminated implicit ThreadLocal label merging to fix several critical issues:
    • Cross-thread operations could lead to assertion errors, missing labels, or infinite loops
    • Closing a ScopedContext on a different thread than where it was created caused unpredictable behavior
    • Thread pools could inherit unexpected labels from previous operations
  • Now requires explicit context management:

    // Old v1 approach (implicit merging through ThreadLocal)
    try (ScopedContext ctx = new ScopedContext(new LabelsSet("request_id", "239"))) {
        try (ScopedContext ctx2 = new ScopedContext(new LabelsSet("op", "doSomething"))) {
            doSomething(); // Runs with BOTH "request_id" and "op" labels automatically
        }
    }
    
    // New v2 approach (explicit passing of parent context is optional)
    try (ScopedContext ctx1 = new ScopedContext(new LabelsSet("request_id", "239"))) {
        // Option 1: Create new context with ALL needed labels (will NOT restore ctx1 when closed)
        try (ScopedContext ctx2 = new ScopedContext(new LabelsSet("request_id", "239", "op", "doSomething"))) {
            doSomething();
            // When ctx2 is closed, ctx1 will NOT be automatically restored
        }
    
        // Option 2: Pass parent context (will NOT merge labels, but will restore parent context when closed)
        try (ScopedContext ctx2 = new ScopedContext(new LabelsSet("op", "doSomething"), ctx1)) {
            // This runs with ONLY "op" label, NOT "request_id"
            // When ctx2 is closed, ctx1 will be automatically restored
            doSomething();
        }
    }

  • Added new ConstantContext class for static, low-cardinality labels:

    // For static, HTTP route-related labels that don't change
    private static final ConstantContext ctx = ConstantContext.of(new LabelsSet(
        "service", "user-api",
        "path", "/api/users/{id}",
        "method", "GET"
    ));
    
    // Later in your code:
    try {
        ctx.activate();
        // Do work with this context active
    } finally {
        ctx.deactivate();
    }

  • Migration Guide:
    1. Update import statements from io.pyroscope.labels to io.pyroscope.labels.v2
    2. Review all ScopedContext usage to ensure proper context passing
    3. Consider using ConstantContext for static, low-cardinality labels
    4. Ensure all contexts are properly closed in the same thread where they were created

New Features

• JFR Profiler Support (8eb09cb): Added support for Java Flight Recorder (JFR) profiler (#136) @kcrimson
• Tracing Integration: Added support for setting spanId and spanName in profiling context using registerConstant (#193)

  // Register string constants for efficient storage and retrieval
  long spanName = Pyroscope.LabelsWrapper.registerConstant("MySpanName");
  
  // Set tracing context with spanId and spanName
  PyroscopeAsyncProfiler.getAsyncProfiler().setTracingContext(spanId, spanName);

Improvements

• Architecture Improvements:
  • Added ProfilerDelegate interface (2611f12) to improve extensibility