The Plumbr Agent API allows to create transactions with a custom lifecycle and change the properties of transactions created automatically by the Plumbr Agent.

Span represents some time that the application has spent executing in one thread. Spans may be started and finished. Once a span starts, it becomes associated with the current processing thread and all root causes, which are detected within that thread are associated with the active span.

A span may contain any number of child spans. Child spans may be associated with threads either in the same JVM, or in a different JVM, which also is monitored by the Plumbr Java Agent.

A span may have metadata associated with it, which is shown in the single transaction view of an unhealthy transaction which that span belongs to.

A Transaction is a tree of spans, which consists of a root span and all of its children. The transaction has some additional properties that describe that tree of spans. These properties include:

• a transaction ID (a UUID, generated automatically)
• an application name (taken from the root span)
• a service name (taken from the root span)
• an identifier of a user (taken from the root span)

This API is useful in the following scenarios:

1. When Plumbr Agent fails to automatically discover transactions in a given application. In this case, the transaction should be created manually by first calling {@link eu.plumbr.api.Plumbr#newSpan()}, then configuring the service name and application of the span and calling {@link eu.plumbr.api.Span#start()} to start it and {@link eu.plumbr.api.Span#finish()} to end it.
2. When Plumbr Agent is able to detect transactions, but fails to assign meaningful service name, application or user ID to them. In this case, {@link eu.plumbr.api.Plumbr#getCurrentSpan()} should be called to get a reference to the automatically created span and then the properties of that span be set with the corresponding methods in {@link eu.plumbr.api.Span}.
3. When Plumbr is able to detect transactions, but is unable to automatically detect if they fail or associate the correct exception with the failure. In this case, {@link eu.plumbr.api.Plumbr#getCurrentSpan()} should be called to get a reference to the automatically created span and then {@link eu.plumbr.api.Span#fail(Throwable)} be called to mark the span as failed and to optionally associate a specific exception as a root cause for the failure.
4. When a request made from a transaction causes a new transaction in a remote application where linking it as a child span into the first transaction is desired. In this case, the caller should create a child span by calling first {@link eu.plumbr.api.Span#createChildSpan()} and then serializing it using {@link eu.plumbr.api.SpanSerializer}. This serialized span can then be included in the request to the other application and deserialized there with {@link eu.plumbr.api.SpanSerializer} and should then be started and finished manually.