Overview (agent-api 19.12.18 API)

Packages
Package	Description
eu.plumbr.api	Main classes and interfaces for the Plumbr Java Agent API.
eu.plumbr.api.noop	Null-safe empty implementation of the Agent API.

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:

When Plumbr Agent fails to automatically discover transactions in a given application. In this case, the transaction should be created manually by first calling Plumbr.newSpan(), then configuring the service name and application of the span and calling Span.start() to start it and Span.finish() to end it.
When Plumbr Agent is able to detect transactions, but fails to assign meaningful service name, application or user ID to them. In this case, 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 Span.
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, Plumbr.getCurrentSpan() should be called to get a reference to the automatically created span and then 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.
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 Span.createChildSpan() and then serializing it using SpanSerializer. This serialized span can then be included in the request to the other application and deserialized there with SpanSerializer and should then be started and finished manually.