package jdk.jfr;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Event field annotation, specifies that the value carries contextual
 * information.
 * <p>
 * Contextual information is data that applies to all events happening in the
 * same thread from the beginning to the end of the event with a field annotated
 * with {@code Contextual}.
 * <p>
 * For example, to trace requests or transactions in a system, a trace event can
 * be created to provide context.
 * {@snippet class = "Snippets" region = "ContextualTrace"}
 * <p>
 * To track details within an order service, an order event can be created where
 * only the order ID provides context.
 * {@snippet class = "Snippets" region = "ContextualOrder"}
 * <p>
 * If an order in the order service stalls due to lock contention, a user
 * interface can display contextual information together with the
 * JavaMonitorEnter event to simplify troubleshooting, for example:
 * {@snippet lang=text :
 *   $ jfr print --events JavaMonitorEnter recording.jfr
 *   jdk.JavaMonitorEnter {
 *     Context: Trace.id = "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
 *     Context: Trace.name = "POST /checkout/place-order"
 *     Context: Order.id = 314159
 *     startTime = 17:51:29.038 (2025-02-07)
 *     duration = 50.56 ms
 *     monitorClass = java.util.ArrayDeque (classLoader = bootstrap)
 *    previousOwner = "Order Thread" (javaThreadId = 56209, virtual = true)
 *    address = 0x60000232ECB0
 *    eventThread = "Order Thread" (javaThreadId = 52613, virtual = true)
 *    stackTrace = [
 *      java.util.zip.ZipFile$CleanableResource.getInflater() line: 685
 *      java.util.zip.ZipFile$ZipFileInflaterInputStream.<init>(ZipFile) line: 388
 *      java.util.zip.ZipFile.getInputStream(ZipEntry) line: 355
 *      java.util.jar.JarFile.getInputStream(ZipEntry) line: 833
 *      ...
 *    ]
 *   }
 * }
 * <p>
 * The difference between {@link Relational} and {@link Contextual} annotations
 * is that {@link Relational} ties event data together to form a global data
 * structure, similar to a foreign key in a relational database, but
 * {@link Contextual} represents a state that applies to all events that happen
 * at the same time, in the same thread. A field can be both contextual and
 * relational at the same time.
 * <p>
 * A contextual field may incur overhead on a parser reading a recording file,
 * since it must track active context, so it should be used sparingly and only
 * where appropriate.
 *
 * @since 25
 */
@MetadataDefinition
@Label("Context")
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface Contextual {
}