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: {@link org.glassfish.contextpropagation.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 {@link ContextManager}.
@see org.glassfish.contextpropagation.Location