001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.tracing;
018
019
020import org.apache.juneau.http.tracing.TraceContextCarrier;
021import static org.apache.juneau.commons.utils.Shorts.*;
022
023/**
024 * Neutral, dependency-free helper for stamping a caller's current trace context into an arbitrary
025 * {@link TraceContextCarrier}.
026 *
027 * <p>
028 * {@code juneau-rest-server} has no first-party call site for this helper &mdash; it exists so a
029 * future MCP-client (or any other non-HTTP caller) adapter can inject the active trace context into
030 * whatever carrier it builds (for example a {@code RequestMeta} being sent as a JSON-RPC request's
031 * {@code params._meta}) without that adapter depending on OpenTelemetry. The adapter depends only on
032 * this class and the installed {@link TracerHook}.
033 *
034 * <h5 class='topic'>Off-by-default contract</h5>
035 *
036 * <p>
037 * {@link #inject(TracerHook, TraceContextCarrier)} does nothing but null-check its arguments and
038 * delegate to {@link TracerHook#inject(TraceContextCarrier)}. Against {@link NoOpTracerHook} (or any
039 * bridge that does not override {@code inject}), the default no-op implementation writes nothing to
040 * the carrier &mdash; only a bridge with an actual trace context to render (for example the
041 * OpenTelemetry bridge in {@code juneau-rest-server-tracing-otel}) writes {@code traceparent} /
042 * {@code tracestate} / {@code baggage} keys.
043 *
044 * <h5 class='section'>See Also:</h5><ul>
045 *    <li class='jc'>{@link TraceContextCarrier}
046 *    <li class='jc'>{@link TracerHook}
047 *    <li class='link'><a class="doclink" href="https://www.w3.org/TR/trace-context/">W3C Trace Context</a>
048 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerObservability">Observability — Micrometer + OpenTelemetry</a>
049 * </ul>
050 *
051 * @since 10.0.0
052 */
053public final class TraceContexts {
054
055   private TraceContexts() {}
056
057   /**
058    * Injects the caller's current trace context (as understood by <c>tracer</c>) into <c>carrier</c>.
059    *
060    * @param tracer The {@link TracerHook} whose active trace context (if any) should be rendered.
061    *    Must not be <jk>null</jk>.
062    * @param carrier The {@link TraceContextCarrier} to write into. Must not be <jk>null</jk>.
063    */
064   public static void inject(TracerHook tracer, TraceContextCarrier carrier) {
065      reqnn("tracer", tracer);
066      reqnn("carrier", carrier);
067      tracer.inject(carrier);
068   }
069}