Skip to content
This repository was archived by the owner on Oct 3, 2023. It is now read-only.

Commit 1ea277c

Browse files
chingor13chingor13
authored
Add SpanData read-only class (#149)
1 parent 842bbc5 commit 1ea277c

File tree

2 files changed

+372
-0
lines changed

2 files changed

+372
-0
lines changed

‎src/Trace/SpanData.php‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
<?php
2+
/**
3+
* Copyright 2018 OpenCensus Authors
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
namespace OpenCensus\Trace;
19+
20+
/**
21+
* This plain PHP class represents a read-only version of a single timed event
22+
* within a Trace. Spans can be nested and form a trace tree. Often, a trace
23+
* contains a root span that describes the end-to-end latency of an operation
24+
* and, optionally, one or more subspans for its suboperations. Spans do not
25+
* need to be contiguous. There may be gaps between spans in a trace.
26+
*/
27+
class SpanData
28+
{
29+
/**
30+
* Unique identifier for a trace. All spans from the same Trace share the
31+
* same `traceId`. 16-byte value encoded as a hex string.
32+
*
33+
* @var string
34+
*/
35+
private $traceId;
36+
37+
/**
38+
* Unique identifier for a span within a trace, assigned when the span is
39+
* created. 8-byte value encoded as a hex string.
40+
*
41+
* @var string
42+
*/
43+
private $spanId;
44+
45+
/**
46+
* The `spanId` of this span's parent span. If this is a root span, then
47+
* this field must be empty. 8-byte value encoded as a hex string.
48+
*
49+
* @var string
50+
*/
51+
private $parentSpanId;
52+
53+
/**
54+
* A description of the span's operation.
55+
*
56+
* For example, the name can be a qualified method name or a file name
57+
* and a line number where the operation is called. A best practice is to
58+
* use the same display name within an application and at the same call
59+
* point. This makes it easier to correlate spans in different traces.
60+
*
61+
* @var string
62+
*/
63+
private $name;
64+
65+
/**
66+
* @var array A set of attributes, each in the format `[KEY]:[VALUE]`.
67+
*/
68+
private $attributes = [];
69+
70+
/**
71+
* The start time of the span. On the client side, this is the time kept by
72+
* the local machine where the span execution starts. On the server side,
73+
* this is the time when the server's application handler starts running.
74+
*
75+
* @var \DateTimeInterface
76+
*/
77+
private $startTime;
78+
79+
80+
/**
81+
* The end time of the span. On the client side, this is the time kept by
82+
* the local machine where the span execution ends. On the server side, this
83+
* is the time when the server application handler stops running.
84+
*
85+
* @var \DateTimeInterface
86+
*/
87+
private $endTime;
88+
89+
/**
90+
* Stack trace captured at the start of the span. This is in the format of
91+
* `debug_backtrace`.
92+
*
93+
* @var array
94+
*/
95+
private $stackTrace = [];
96+
97+
/**
98+
* A collection of `TimeEvent`s. A `TimeEvent` is a time-stamped annotation
99+
* on the span, consisting of either user-supplied key:value pairs, or
100+
* details of a message sent/received between Spans
101+
*
102+
* @var TimeEvent[]
103+
*/
104+
private $timeEvents = [];
105+
106+
/**
107+
* A collection of links, which are references from this span to a span
108+
* in the same or different trace.
109+
*
110+
* @var Link[]
111+
*/
112+
private $links = [];
113+
114+
/**
115+
* An optional final status for this span.
116+
*
117+
* @var Status
118+
*/
119+
private $status;
120+
121+
/**
122+
* A highly recommended but not required flag that identifies when a trace
123+
* crosses a process boundary. True when the parentSpanId belongs to the
124+
* same process as the current span.
125+
*
126+
* @var bool
127+
*/
128+
private $sameProcessAsParentSpan;
129+
130+
/**
131+
* Instantiate a new SpanData instance.
132+
*
133+
* @param string $name The name of the span.
134+
* @param string $traceId The ID of the trace in hexadecimal.
135+
* @param string $spanId The ID of the span in hexadecimal.
136+
* @param \DateTimeInterface $startTime Start time of the span.
137+
* @param \DateTimeInterface $endTime End time of the span.
138+
* @param array $options [optional] Configuration options.
139+
*
140+
* @type string $parentSpanId ID of the parent span if any in
141+
* hexadecimal.
142+
* @type array $attributes Associative array of $attribute => $value
143+
* to attach to this span.
144+
* @type array $stackTrace Stacktrace in `debug_backtrace` format.
145+
* @type TimeEvent[] $timeEvents Timing events.
146+
* @type Link[] $links Link references.
147+
* @type Status $status The final status for this span.
148+
* @type bool $sameProcessAsParentSpan True when the parentSpanId
149+
* belongs to the same process as the current span.
150+
*/
151+
public function __construct(
152+
$name,
153+
$traceId,
154+
$spanId,
155+
\DateTimeInterface $startTime,
156+
\DateTimeInterface $endTime,
157+
array $options = []
158+
) {
159+
$options += [
160+
'parentSpanId' => null,
161+
'attributes' => [],
162+
'timeEvents' => [],
163+
'links' => [],
164+
'status' => null,
165+
'sameProcessAsParentSpan' => null,
166+
'stackTrace' => []
167+
];
168+
169+
$this->name = $name;
170+
$this->traceId = $traceId;
171+
$this->spanId = $spanId;
172+
$this->startTime = $startTime;
173+
$this->endTime = $endTime;
174+
175+
$this->parentSpanId = $options['parentSpanId'];
176+
$this->attributes = $options['attributes'];
177+
$this->stackTrace = $options['stackTrace'];
178+
$this->timeEvents = $options['timeEvents'];
179+
$this->links = $options['links'];
180+
$this->status = $options['status'];
181+
$this->sameProcessAsParentSpan = $options['sameProcessAsParentSpan'];
182+
}
183+
184+
/**
185+
* Retrieve the start time for this span.
186+
*
187+
* @return \DateTimeInterface
188+
*/
189+
public function startTime()
190+
{
191+
return $this->startTime;
192+
}
193+
194+
/**
195+
* Retrieve the end time for this span.
196+
*
197+
* @return \DateTimeInterface
198+
*/
199+
public function endTime()
200+
{
201+
return $this->endTime;
202+
}
203+
204+
/**
205+
* Retrieve the ID of this span's trace.
206+
*
207+
* @return string
208+
*/
209+
public function traceId()
210+
{
211+
return $this->traceId;
212+
}
213+
214+
/**
215+
* Retrieve the ID of this span.
216+
*
217+
* @return string
218+
*/
219+
public function spanId()
220+
{
221+
return $this->spanId;
222+
}
223+
224+
/**
225+
* Retrieve the ID of this span's parent if it exists.
226+
*
227+
* @return string
228+
*/
229+
public function parentSpanId()
230+
{
231+
return $this->parentSpanId;
232+
}
233+
234+
/**
235+
* Retrieve the name of this span.
236+
*
237+
* @return string
238+
*/
239+
public function name()
240+
{
241+
return $this->name;
242+
}
243+
244+
/**
245+
* Return the attributes for this span.
246+
*
247+
* @return array
248+
*/
249+
public function attributes()
250+
{
251+
return $this->attributes;
252+
}
253+
254+
/**
255+
* Return the time events for this span.
256+
*
257+
* @return TimeEvent[]
258+
*/
259+
public function timeEvents()
260+
{
261+
return $this->timeEvents;
262+
}
263+
264+
/**
265+
* Return the links for this span.
266+
*
267+
* @return Link[]
268+
*/
269+
public function links()
270+
{
271+
return $this->links;
272+
}
273+
274+
/**
275+
* Retrieve the final status for this span.
276+
*
277+
* @return Status
278+
*/
279+
public function status()
280+
{
281+
return $this->status;
282+
}
283+
284+
/**
285+
* Retrieve the stackTrace at the moment this span was created
286+
*
287+
* @return array
288+
*/
289+
public function stackTrace()
290+
{
291+
return $this->stackTrace;
292+
}
293+
294+
/**
295+
* Whether or not this span is in the same process as its parent.
296+
*
297+
* @return bool
298+
*/
299+
public function sameProcessAsParentSpan()
300+
{
301+
return $this->sameProcessAsParentSpan;
302+
}
303+
}

‎tests/unit/Trace/SpanDataTest.php‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
<?php
2+
/**
3+
* Copyright 2018 OpenCensus Authors
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
namespace OpenCensus\Tests\Unit\Trace;
19+
20+
use OpenCensus\Trace\Annotation;
21+
use OpenCensus\Trace\Link;
22+
use OpenCensus\Trace\MessageEvent;
23+
use OpenCensus\Trace\SpanData;
24+
use OpenCensus\Trace\Status;
25+
26+
/**
27+
* @group trace
28+
*/
29+
class SpanDataTest extends \PHPUnit_Framework_TestCase
30+
{
31+
public function testDefaults()
32+
{
33+
$startTime = new \DateTime();
34+
$endTime = new \DateTime();
35+
$spanData = new SpanData('span-name', 'aaa', 'bbb', $startTime, $endTime);
36+
$this->assertEquals('span-name', $spanData->name());
37+
$this->assertEquals('aaa', $spanData->traceId());
38+
$this->assertEquals('bbb', $spanData->spanId());
39+
$this->assertEquals($startTime, $spanData->startTime());
40+
$this->assertEquals($endTime, $spanData->endTime());
41+
}
42+
43+
/**
44+
* @dataProvider spanDataOptions
45+
*/
46+
public function testAttributes($key, $value)
47+
{
48+
$startTime = new \DateTime();
49+
$endTime = new \DateTime();
50+
$spanData = new SpanData('span-name', 'aaa', 'bbb', $startTime, $endTime, [
51+
$key => $value
52+
]);
53+
$this->assertEquals($value, call_user_func([$spanData, $key]));
54+
}
55+
56+
public function spanDataOptions()
57+
{
58+
return [
59+
['attributes', ['foo' => 'bar']],
60+
['timeEvents', [
61+
new Annotation('description'),
62+
new MessageEvent(MessageEvent::TYPE_SENT, 'message-id')]
63+
],
64+
['links', [new Link('traceId', 'spanId')]],
65+
['status', new Status(200, 'OK')],
66+
['stackTrace', debug_backtrace()]
67+
];
68+
}
69+
}

0 commit comments

Comments
 (0)