1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
#ifndef OPENTRACING_PROPAGATION_H
#define OPENTRACING_PROPAGATION_H
#include <opentracing/string_view.h>
#include <opentracing/symbols.h>
#include <opentracing/util.h>
#include <opentracing/version.h>
#include <functional>
#include <memory>
#include <string>
#include <system_error>
namespace opentracing {
BEGIN_OPENTRACING_ABI_NAMESPACE
class Tracer;
class SpanContext;
enum class SpanReferenceType {
// ChildOfRef refers to a parent Span that caused *and* somehow depends
// upon the new child Span. Often (but not always), the parent Span cannot
// finish until the child Span does.
//
// An timing diagram for a ChildOfRef that's blocked on the new Span:
//
// [-Parent Span---------]
// [-Child Span----]
//
// See http://opentracing.io/spec/
//
// See opentracing.ChildOf()
ChildOfRef = 1,
// FollowsFromRef refers to a parent Span that does not depend in any way
// on the result of the new child Span. For instance, one might use
// FollowsFromRefs to describe pipeline stages separated by queues,
// or a fire-and-forget cache insert at the tail end of a web request.
//
// A FollowsFromRef Span is part of the same logical trace as the new Span:
// i.e., the new Span is somehow caused by the work of its FollowsFromRef.
//
// All of the following could be valid timing diagrams for children that
// "FollowFrom" a parent.
//
// [-Parent Span-] [-Child Span-]
//
//
// [-Parent Span--]
// [-Child Span-]
//
//
// [-Parent Span-]
// [-Child Span-]
//
// See http://opentracing.io/spec/
//
// See opentracing.FollowsFrom()
FollowsFromRef = 2
};
// Returns the std::error_category class used for opentracing propagation
// errors.
//
// See
// http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html
// https://ned14.github.io/boost.outcome/md_doc_md_03-tutorial_b.html
OPENTRACING_API const std::error_category& propagation_error_category();
// `invalid_span_context_error` occurs when Tracer::Inject() is asked to operate
// on a SpanContext which it is not prepared to handle (for example, since it
// was created by a different tracer implementation).
const std::error_code invalid_span_context_error(1,
propagation_error_category());
// `invalid_carrier_error` occurs when Tracer::Inject() or Tracer::Extract()
// implementations expect a different type of `carrier` than they are given.
const std::error_code invalid_carrier_error(2, propagation_error_category());
// `span_context_corrupted_error` occurs when the `carrier` passed to
// Tracer::Extract() is of the expected type but is corrupted.
const std::error_code span_context_corrupted_error(
3, propagation_error_category());
// `key_not_found_error` occurs when TextMapReader::LookupKey fails to find
// an entry for the provided key.
const std::error_code key_not_found_error(4, propagation_error_category());
// `lookup_key_not_supported_error` occurs when TextMapReader::LookupKey is
// not supported for the provided key.
const std::error_code lookup_key_not_supported_error(
5, propagation_error_category());
// TextMapReader is the Extract() carrier for the TextMap builtin format. With
// it, the caller can decode a SpanContext from entries in a propagated map of
// Unicode strings.
//
// See the HTTPHeaders examples.
class TextMapReader {
public:
virtual ~TextMapReader() = default;
// LookupKey returns the value for the specified `key` if available. If no
// such key is present, it returns `key_not_found_error`.
//
// TextMapReaders are not required to implement this method. If not supported,
// the function returns `lookup_key_not_supported_error`.
//
// Tracers may use this as an alternative to `ForeachKey` as a faster way to
// extract span context.
virtual expected<string_view> LookupKey(string_view /*key*/) const {
return make_unexpected(lookup_key_not_supported_error);
}
// ForeachKey returns TextMap contents via repeated calls to the `f`
// function. If any call to `f` returns an error, ForeachKey terminates and
// returns that error.
//
// NOTE: The backing store for the TextMapReader may contain data unrelated
// to SpanContext. As such, Inject() and Extract() implementations that
// call the TextMapWriter and TextMapReader interfaces must agree on a
// prefix or other convention to distinguish their own key:value pairs.
//
// The "foreach" callback pattern reduces unnecessary copying in some cases
// and also allows implementations to hold locks while the map is read.
virtual expected<void> ForeachKey(
std::function<expected<void>(string_view key, string_view value)> f)
const = 0;
};
// TextMapWriter is the Inject() carrier for the TextMap builtin format. With
// it, the caller can encode a SpanContext for propagation as entries in a map
// of unicode strings.
//
// See the HTTPHeaders examples.
class TextMapWriter {
public:
virtual ~TextMapWriter() = default;
// Set a key:value pair to the carrier. Multiple calls to Set() for the
// same key leads to undefined behavior.
//
// NOTE: The backing store for the TextMapWriter may contain data unrelated
// to SpanContext. As such, Inject() and Extract() implementations that
// call the TextMapWriter and TextMapReader interfaces must agree on a
// prefix or other convention to distinguish their own key:value pairs.
virtual expected<void> Set(string_view key, string_view value) const = 0;
};
// HTTPHeadersReader is the Extract() carrier for the HttpHeaders builtin
// format. With it, the caller can decode a SpanContext from entries in HTTP
// request headers.
//
// For example, Extract():
//
// const Tracer& tracer = /* some tracer */
// const HTTPHeadersReader& carrier_reader = /* some carrier */
// auto span_context_maybe = tracer.Extract(carrier_reader);
// if (!span_context_maybe) {
// throw std::runtime_error(span_context_maybe.error().message());
// }
// auto span = tracer.StartSpan("op",
// { ChildOf(span_context_maybe->get()) });
class HTTPHeadersReader : public TextMapReader {};
// HTTPHeadersWriter is the Inject() carrier for the TextMap builtin format.
// With it, the caller can encode a SpanContext for propagation as entries in
// http request headers
//
// For example, Inject():
//
// const HTTPHeadersWriter& carrier_writer = /* some carrier */
// auto was_successful = span.tracer().Inject(span,
// carrier_writer);
// if (!was_successful) {
// throw std::runtime_error(was_successful.error().message());
// }
class HTTPHeadersWriter : public TextMapWriter {};
// CustomCarrierReader is the Extract() carrier for a custom format. With it,
// the caller can decode a SpanContext from entries in a custom protocol.
class CustomCarrierReader {
public:
virtual ~CustomCarrierReader() = default;
// Extract is expected to specialize on the tracer implementation so as to
// most efficiently decode its context.
virtual expected<std::unique_ptr<SpanContext>> Extract(
const Tracer& tracer) const = 0;
};
// CustomCarrierWriter is the Inject() carrier for a custom format. With it,
// the caller can encode a SpanContext for propagation as entries in a custom
// protocol.
class CustomCarrierWriter {
public:
virtual ~CustomCarrierWriter() = default;
// Inject is expected to specialize on the tracer implementation so as to most
// efficiently encode its context.
virtual expected<void> Inject(const Tracer& tracer,
const SpanContext& sc) const = 0;
};
END_OPENTRACING_ABI_NAMESPACE
} // namespace opentracing
#endif // OPENTRACING_PROPAGATION_H
|
