io.opentelemetry.context.propagation.HttpTextFormat Maven / Gradle / Ivy
Show all versions of lightstep-opentelemetry-auto-exporter Show documentation
/*
* Copyright 2019, OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.opentelemetry.context.propagation;
import shaded.shaded.io.grpc.Context;
import java.util.List;
import javax.annotation.Nullable;
import javax.annotation.concurrent.ThreadSafe;
/**
* Injects and extracts a value as text into carriers that travel in-band across process boundaries.
* Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as
* RPC/HTTP request headers.
*
* The carrier of propagated data on both the client (injector) and server (extractor) side is
* usually an http request. Propagation is usually implemented via library- specific request
* interceptors, where the client-side injects values and the server-side extracts them.
*
*
Specific concern values (traces, correlations, etc) will be read from the specified {@code
* Context}, and resulting values will be stored in a new {@code Context} upon extraction. It is
* recommended to use a single {@code Context.Key} to store the entire concern data:
*
*
{@code
* public static final Context.Key CONCERN_KEY = Context.key("my-concern-key");
* public MyConcernPropagator implements HttpTextFormat {
* public void inject(Context context, C carrier, Setter setter) {
* Object concern = CONCERN_KEY.get(context);
* // Use concern in the specified context to propagate data.
* }
* public Context extract(Context context, C carrier, Getter setter) {
* // Use setter to get the data from the carrier.
* return context.withValue(CONCERN_KEY, concern);
* }
* }
* }
*
* @since 0.1.0
*/
@ThreadSafe
public interface HttpTextFormat {
/**
* The propagation fields defined. If your carrier is reused, you should delete the fields here
* before calling {@link #inject(Context, Object, Setter)} )}.
*
* For example, if the carrier is a single-use or immutable request object, you don't need to
* clear fields as they couldn't have been set before. If it is a mutable, retryable object,
* successive calls should clear these fields first.
*
* @return list of fields that will be used by this formatter.
* @since 0.1.0
*/
// The use cases of this are:
// * allow pre-allocation of fields, especially in systems like gRPC Metadata
// * allow a single-pass over an iterator
List fields();
/**
* Injects the value downstream, for example as HTTP headers. The carrier may be null to
* facilitate calling this method with a lambda for the {@link Setter}, in which case that null
* will be passed to the {@link Setter} implementation.
*
* @param context the {@code Context} containing the value to be injected.
* @param carrier holds propagation fields. For example, an outgoing message or http request.
* @param setter invoked for each propagation key to add or remove.
* @param carrier of propagation fields, such as an http request
* @since 0.1.0
*/
void inject(Context context, @Nullable C carrier, Setter setter);
/**
* Class that allows a {@code HttpTextFormat} to set propagated fields into a carrier.
*
* {@code Setter} is stateless and allows to be saved as a constant to avoid runtime
* allocations.
*
* @param carrier of propagation fields, such as an http request
* @since 0.1.0
*/
interface Setter {
/**
* Replaces a propagated field with the given value.
*
* For example, a setter for an {@link java.net.HttpURLConnection} would be the method
* reference {@link java.net.HttpURLConnection#addRequestProperty(String, String)}
*
* @param carrier holds propagation fields. For example, an outgoing message or http request. To
* facilitate implementations as java lambdas, this parameter may be null.
* @param key the key of the field.
* @param value the value of the field.
* @since 0.1.0
*/
void set(@Nullable C carrier, String key, String value);
}
/**
* Extracts the value from upstream. For example, as http headers.
*
*
If the value could not be parsed, the underlying implementation will decide to set an object
* representing either an empty value, an invalid value, or a valid value. Implementation must not
* set {@code null}.
*
* @param context the {@code Context} used to store the extracted value.
* @param carrier holds propagation fields. For example, an outgoing message or http request.
* @param getter invoked for each propagation key to get.
* @param carrier of propagation fields, such as an http request.
* @return the {@code Context} containing the extracted value.
* @since 0.1.0
*/
Context extract(Context context, C carrier, Getter getter);
/**
* Interface that allows a {@code HttpTextFormat} to read propagated fields from a carrier.
*
* {@code Getter} is stateless and allows to be saved as a constant to avoid runtime
* allocations.
*
* @param carrier of propagation fields, such as an http request.
* @since 0.1.0
*/
interface Getter {
/**
* Returns the first value of the given propagation {@code key} or returns {@code null}.
*
* @param carrier carrier of propagation fields, such as an http request.
* @param key the key of the field.
* @return the first value of the given propagation {@code key} or returns {@code null}.
* @since 0.1.0
*/
@Nullable
String get(C carrier, String key);
}
}