Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add cats-effect instrumentation #13576

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

iRevive
Copy link

@iRevive iRevive commented Mar 23, 2025

Closes #10599.

Hey folks.

Cats Effect is a high-performance, asynchronous, composable framework for building real-world applications in a purely functional style within the Typelevel ecosystem.

How the instrumentation works

Cats Effect has its context propagation mechanism known as IOLocal. 3.6.0 release provides a way to represent IOLocal as a ThreadLocal, which creates an opportunity to manipulate the context from the outside.

  • Agent instruments the constructor of IORuntime and stores a ThreadLocal representation of the IOLocal[Context] in the bootstrap classloader, so the agent and application both access the same instance
  • Instrumentation installs a custom ContextStorage wrapper (for the agent context storage). This wrapper uses FiberLocalContextHelper to retrieve the fiber's current context (if available)
  • Agent instruments IOFiber's constructor and starts the fiber with the currently available context

@iRevive iRevive requested a review from a team as a code owner March 23, 2025 19:23
import cats.effect.IOLocal;
import io.opentelemetry.javaagent.instrumentation.opentelemetryapi.context.AgentContextStorage;

public class IoLocalContextSingleton {
Copy link
Author

@iRevive iRevive Mar 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It must be defined in a common package so we can lately reuse it to instrument otel4s.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is a prototype: iRevive@b2f6501

@iRevive
Copy link
Author

iRevive commented Mar 23, 2025

Some tests have failed with the following error:

java.lang.IllegalStateException: Cannot write to this reference for cats.effect.IO arg0 in read-only context

I assume some VMs aren't happy with the body modification of IO?


@Advice.OnMethodEnter(suppress = Throwable.class)
public static void onEnter() {
FiberLocalContextHelper.initialize(
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if you have deployed 2 wars on tomcat that use this library, won't this break? Messing with the context storage is unusual, my hunch is that this is not a good idea. Typically such instrumentations restore the otel context when fiber starts running on a thread and save the context when it stops using the thread.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a valid concern indeed.

deployed 2 wars on tomcat that use this library

If I understand correctly, each deployment (app) will have its own classloader, but the bootstrap will still be shared.
If that's the case, my implementation won't work, I'm afraid.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suppose I don't find a proper way to make the instrumentation work. Can I distribute the current implementation as a third-party extension? Can the extension have access to the bootstrap loader?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can the extension have access to the bootstrap loader?

Not directly, but you could try using byte-buddy to define the class you need in boot loader or you could experiment with Instrumentation.appendToBootstrapClassLoaderSearch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Support context propagation in Cats Effect library (Scala)
2 participants