woocommerce-pos / vendor_prefixed / sentry / sentry / src / Tracing / Span.php

Span.php in WCPOS – Point of Sale (POS) plugin for WooCommerce 1.10.24, at vendor_prefixed/sentry/sentry/src/Tracing/Span.php

521 lines 14.2 KB

Raw Download Zip

1	<?php
2
3	declare (strict_types=1);
4	namespace WCPOS\Vendor\Sentry\Tracing;
5
6	use WCPOS\Vendor\Sentry\EventId;
7	use WCPOS\Vendor\Sentry\SentrySdk;
8	use WCPOS\Vendor\Sentry\State\Scope;
9	use WCPOS\Vendor\Sentry\Unit;
10	/**
11	* This class stores all the information about a span.
12	*
13	* @phpstan-type MetricsSummary array{
14	* min: int\|float,
15	* max: int\|float,
16	* sum: int\|float,
17	* count: int,
18	* tags: array<string>,
19	* }
20	*/
21	class Span
22	{
23	/**
24	* Maximum number of flags allowed. We only track the first flags set.
25	*
26	* @internal
27	*/
28	public const MAX_FLAGS = 10;
29	/**
30	* @var SpanId Span ID
31	*/
32	protected $spanId;
33	/**
34	* @var TraceId Trace ID
35	*/
36	protected $traceId;
37	/**
38	* @var string\|null Description of the span
39	*/
40	protected $description;
41	/**
42	* @var string\|null Operation of the span
43	*/
44	protected $op;
45	/**
46	* @var SpanStatus\|null Completion status of the span
47	*/
48	protected $status;
49	/**
50	* @var SpanId\|null ID of the parent span
51	*/
52	protected $parentSpanId;
53	/**
54	* @var bool\|null Has the sample decision been made?
55	*/
56	protected $sampled;
57	/**
58	* @var array<string, string> A List of tags associated to this span
59	*/
60	protected $tags = [];
61	/**
62	* @var array<string, bool> A List of flags associated to this span
63	*/
64	protected $flags = [];
65	/**
66	* @var array<string, mixed> An arbitrary mapping of additional metadata
67	*/
68	protected $data = [];
69	/**
70	* @var float Timestamp in seconds (epoch time) indicating when the span started
71	*/
72	protected $startTimestamp;
73	/**
74	* @var float\|null Timestamp in seconds (epoch time) indicating when the span ended
75	*/
76	protected $endTimestamp;
77	/**
78	* @var SpanRecorder\|null Reference instance to the {@see SpanRecorder}
79	*/
80	protected $spanRecorder;
81	/**
82	* @var Transaction\|null The transaction containing this span
83	*/
84	protected $transaction;
85	/**
86	* @var string\|null The trace origin of the span. If no origin is set, the span is considered to be "manual".
87	*
88	* @see https://develop.sentry.dev/sdk/performance/trace-origin/
89	*/
90	protected $origin;
91	/**
92	* Constructor.
93	*
94	* @param SpanContext\|null $context The context to create the span with
95	*
96	* @internal
97	*/
98	public function __construct(?SpanContext $context = null)
99	{
100	if ($context === null) {
101	$this->traceId = TraceId::generate();
102	$this->spanId = SpanId::generate();
103	$this->startTimestamp = \microtime(\true);
104	return;
105	}
106	$this->traceId = $context->getTraceId() ?? TraceId::generate();
107	$this->spanId = $context->getSpanId() ?? SpanId::generate();
108	$this->startTimestamp = $context->getStartTimestamp() ?? \microtime(\true);
109	$this->parentSpanId = $context->getParentSpanId();
110	$this->description = $context->getDescription();
111	$this->op = $context->getOp();
112	$this->status = $context->getStatus();
113	$this->sampled = $context->getSampled();
114	$this->tags = $context->getTags();
115	$this->data = $context->getData();
116	$this->endTimestamp = $context->getEndTimestamp();
117	$this->origin = $context->getOrigin();
118	}
119	/**
120	* Sets the ID of the span.
121	*
122	* @param SpanId $spanId The ID
123	*/
124	public function setSpanId(SpanId $spanId) : self
125	{
126	$this->spanId = $spanId;
127	return $this;
128	}
129	/**
130	* Gets the ID that determines which trace the span belongs to.
131	*/
132	public function getTraceId() : TraceId
133	{
134	return $this->traceId;
135	}
136	/**
137	* Sets the ID that determines which trace the span belongs to.
138	*
139	* @param TraceId $traceId The ID
140	*
141	* @return $this
142	*/
143	public function setTraceId(TraceId $traceId)
144	{
145	$this->traceId = $traceId;
146	return $this;
147	}
148	/**
149	* Gets the ID that determines which span is the parent of the current one.
150	*/
151	public function getParentSpanId() : ?SpanId
152	{
153	return $this->parentSpanId;
154	}
155	/**
156	* Sets the ID that determines which span is the parent of the current one.
157	*
158	* @param SpanId\|null $parentSpanId The ID
159	*
160	* @return $this
161	*/
162	public function setParentSpanId(?SpanId $parentSpanId)
163	{
164	$this->parentSpanId = $parentSpanId;
165	return $this;
166	}
167	/**
168	* Gets the timestamp representing when the measuring started.
169	*/
170	public function getStartTimestamp() : float
171	{
172	return $this->startTimestamp;
173	}
174	/**
175	* Sets the timestamp representing when the measuring started.
176	*
177	* @param float $startTimestamp The timestamp
178	*
179	* @return $this
180	*/
181	public function setStartTimestamp(float $startTimestamp)
182	{
183	$this->startTimestamp = $startTimestamp;
184	return $this;
185	}
186	/**
187	* Gets the timestamp representing when the measuring finished.
188	*/
189	public function getEndTimestamp() : ?float
190	{
191	return $this->endTimestamp;
192	}
193	/**
194	* Gets a description of the span's operation, which uniquely identifies
195	* the span but is consistent across instances of the span.
196	*/
197	public function getDescription() : ?string
198	{
199	return $this->description;
200	}
201	/**
202	* Sets a description of the span's operation, which uniquely identifies
203	* the span but is consistent across instances of the span.
204	*
205	* @param string\|null $description The description
206	*
207	* @return $this
208	*/
209	public function setDescription(?string $description)
210	{
211	$this->description = $description;
212	return $this;
213	}
214	/**
215	* Gets a short code identifying the type of operation the span is measuring.
216	*/
217	public function getOp() : ?string
218	{
219	return $this->op;
220	}
221	/**
222	* Sets a short code identifying the type of operation the span is measuring.
223	*
224	* @param string\|null $op The short code
225	*
226	* @return $this
227	*/
228	public function setOp(?string $op)
229	{
230	$this->op = $op;
231	return $this;
232	}
233	/**
234	* Gets the status of the span/transaction.
235	*/
236	public function getStatus() : ?SpanStatus
237	{
238	return $this->status;
239	}
240	/**
241	* Sets the status of the span/transaction.
242	*
243	* @param SpanStatus\|null $status The status
244	*
245	* @return $this
246	*/
247	public function setStatus(?SpanStatus $status)
248	{
249	$this->status = $status;
250	return $this;
251	}
252	/**
253	* Sets the HTTP status code and the status of the span/transaction.
254	*
255	* @param int $statusCode The HTTP status code
256	*
257	* @return $this
258	*/
259	public function setHttpStatus(int $statusCode)
260	{
261	SentrySdk::getCurrentHub()->configureScope(static function (Scope $scope) use($statusCode) {
262	$scope->setContext('response', ['status_code' => $statusCode]);
263	});
264	$status = SpanStatus::createFromHttpStatusCode($statusCode);
265	if ($status !== SpanStatus::unknownError()) {
266	$this->status = $status;
267	}
268	return $this;
269	}
270	/**
271	* Gets a map of tags for this event.
272	*
273	* @return array<string, string>
274	*/
275	public function getTags() : array
276	{
277	return $this->tags;
278	}
279	/**
280	* Sets a map of tags for this event. This method will merge the given tags with
281	* the existing ones.
282	*
283	* @param array<string, string> $tags The tags
284	*
285	* @return $this
286	*/
287	public function setTags(array $tags)
288	{
289	$this->tags = \array_merge($this->tags, $tags);
290	return $this;
291	}
292	/**
293	* Sets a feature flag associated to this span.
294	*
295	* @return $this
296	*/
297	public function setFlag(string $key, bool $result)
298	{
299	if (\count($this->flags) < self::MAX_FLAGS) {
300	$this->flags[$key] = $result;
301	}
302	return $this;
303	}
304	/**
305	* Gets the ID of the span.
306	*/
307	public function getSpanId() : SpanId
308	{
309	return $this->spanId;
310	}
311	/**
312	* Gets the flag determining whether this span should be sampled or not.
313	*/
314	public function getSampled() : ?bool
315	{
316	return $this->sampled;
317	}
318	/**
319	* Sets the flag determining whether this span should be sampled or not.
320	*
321	* @param bool $sampled Whether to sample or not this span
322	*
323	* @return $this
324	*/
325	public function setSampled(?bool $sampled)
326	{
327	$this->sampled = $sampled;
328	return $this;
329	}
330	/**
331	* Gets a map of arbitrary data or a specific key from the map of data attached to this span.
332	*
333	* @param string\|null $key Select a specific key from the data to return the value of
334	* @param mixed $default When the $key is not found, return this value
335	*
336	* @return ($key is null ? array<string, mixed> : mixed\|null)
337	*/
338	public function getData(?string $key = null, $default = null)
339	{
340	if ($key === null) {
341	$data = $this->data;
342	foreach ($this->flags as $flagKey => $flagValue) {
343	$data["flag.evaluation.{$flagKey}"] = $flagValue;
344	}
345	return $data;
346	}
347	return $this->data[$key] ?? $default;
348	}
349	/**
350	* Sets a map of arbitrary data. This method will merge the given data with the existing one.
351	*
352	* @param array<string, mixed> $data The data
353	*
354	* @return $this
355	*/
356	public function setData(array $data)
357	{
358	$this->data = \array_merge($this->data, $data);
359	return $this;
360	}
361	/**
362	* Gets the data in a format suitable for storage in the "trace" context.
363	*
364	* @return array<string, mixed>
365	*
366	* @phpstan-return array{
367	* data?: array<string, mixed>,
368	* description?: string,
369	* op?: string,
370	* parent_span_id?: string,
371	* span_id: string,
372	* status?: string,
373	* tags?: array<string, string>,
374	* trace_id: string,
375	* origin: string,
376	* }
377	*/
378	public function getTraceContext() : array
379	{
380	$result = ['span_id' => (string) $this->spanId, 'trace_id' => (string) $this->traceId, 'origin' => $this->origin ?? 'manual'];
381	if ($this->parentSpanId !== null) {
382	$result['parent_span_id'] = (string) $this->parentSpanId;
383	}
384	if ($this->description !== null) {
385	$result['description'] = $this->description;
386	}
387	if ($this->op !== null) {
388	$result['op'] = $this->op;
389	}
390	if ($this->status !== null) {
391	$result['status'] = (string) $this->status;
392	}
393	if (!empty($this->data)) {
394	$result['data'] = $this->data;
395	}
396	if (!empty($this->tags)) {
397	$result['tags'] = $this->tags;
398	}
399	return $result;
400	}
401	/**
402	* Sets the finish timestamp on the current span.
403	*
404	* @param float\|null $endTimestamp Takes an endTimestamp if the end should not be the time when you call this function
405	*
406	* @return EventId\|null Finish for a span always returns null
407	*/
408	public function finish(?float $endTimestamp = null) : ?EventId
409	{
410	$this->endTimestamp = $endTimestamp ?? \microtime(\true);
411	return null;
412	}
413	/**
414	* Creates a new {@see Span} while setting the current ID as `parentSpanId`.
415	* Also the `sampled` decision will be inherited.
416	*
417	* @param SpanContext $context The context of the child span
418	*/
419	public function startChild(SpanContext $context) : self
420	{
421	$context = clone $context;
422	$context->setSampled($this->sampled);
423	$context->setParentSpanId($this->spanId);
424	$context->setTraceId($this->traceId);
425	$span = new self($context);
426	$span->transaction = $this->transaction;
427	$span->spanRecorder = $this->spanRecorder;
428	if ($span->spanRecorder !== null) {
429	$span->spanRecorder->add($span);
430	}
431	return $span;
432	}
433	/**
434	* Gets the span recorder attached to this span.
435	*
436	* @internal
437	*/
438	public function getSpanRecorder() : ?SpanRecorder
439	{
440	return $this->spanRecorder;
441	}
442	/**
443	* Detaches the span recorder from this instance.
444	*
445	* @return $this
446	*/
447	public function detachSpanRecorder()
448	{
449	$this->spanRecorder = null;
450	return $this;
451	}
452	/**
453	* @deprecated Metrics are no longer supported. Metrics API is a no-op and will be removed in 5.x.
454	*/
455	public function getMetricsSummary() : array
456	{
457	return [];
458	}
459	/**
460	* @deprecated Metrics are no longer supported. Metrics API is a no-op and will be removed in 5.x.
461	*/
462	public function setMetricsSummary(string $type, string $key, $value, Unit $unit, array $tags) : void
463	{
464	}
465	/**
466	* Sets the trace origin for this span.
467	*/
468	public function getOrigin() : ?string
469	{
470	return $this->origin;
471	}
472	/**
473	* Sets the trace origin of the span.
474	*
475	* @return $this
476	*/
477	public function setOrigin(?string $origin)
478	{
479	$this->origin = $origin;
480	return $this;
481	}
482	/**
483	* Returns the transaction containing this span.
484	*/
485	public function getTransaction() : ?Transaction
486	{
487	return $this->transaction;
488	}
489	/**
490	* Returns a string that can be used for the `sentry-trace` header & meta tag.
491	*/
492	public function toTraceparent() : string
493	{
494	$sampled = '';
495	if ($this->sampled !== null) {
496	$sampled = $this->sampled ? '-1' : '-0';
497	}
498	return \sprintf('%s-%s%s', (string) $this->traceId, (string) $this->spanId, $sampled);
499	}
500	/**
501	* Returns a string that can be used for the W3C `traceparent` header & meta tag.
502	*
503	* @deprecated since version 4.12. To be removed in version 5.0.
504	*/
505	public function toW3CTraceparent() : string
506	{
507	return '';
508	}
509	/**
510	* Returns a string that can be used for the `baggage` header & meta tag.
511	*/
512	public function toBaggage() : string
513	{
514	$transaction = $this->getTransaction();
515	if ($transaction !== null) {
516	return (string) $transaction->getDynamicSamplingContext();
517	}
518	return '';
519	}
520	}
521