The diagnostics Context is the object through which
diagnostics data relevant to the current task are
read and written.
A task is a unit of work being executed by the java
process. Examples include
- responding to an external stimulus such
as a simple http request or web-service request
- executing a scheduled job
A parent task can create sub-tasks the completion of which
may or may not affect the execution of the parent task.
The diagnostics Context of the parent task will propagate
to the child sub-tasks.
Diagnostics data include:
- Location:
Location
provides correlation between a task and its sub-task(s)
- Name-value pairs: Arbitrary name-value pairs that may
be reported in diagnostics features such as logging,
flight recordings, request sampling and tracing and so on.
- Name: The name should use the standard java naming
convention including package name. The name should
be sufficiently clear that consumers of the data
(e.g. the readers of log files, i.e. developers!)
have some good starting point when interpreting the
diagnostics data.
- Value: The value should be as concise as possible.
Only those name-value pairs marked for propagation will
propagate to the diagnostics Contexts of sub-tasks.
It is generally the case that data associated with a
particular name will either always propagate or always
not propagate - i.e. it is either usefully shared with
child Contexts or only makes sense if kept private
to one Context.
The diagnostics Context of the currently executing task can
be obtained from the
ContextManager
.