1# Copyright 2017, OpenCensus Authors
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15from opencensus.trace import base_span
16from opencensus.trace.span_context import generate_span_id
17from opencensus.trace.tracers import base
18
19
20class BlankSpan(base_span.BaseSpan):
21    """A BlankSpan is an individual timed event which forms a node of the trace
22    tree. All operations are no-op.
23
24    :type name: str
25    :param name: The name of the span.
26
27    :type parent_span: :class:`~opencensus.trace.blank_span.BlankSpan`
28    :param parent_span: (Optional) Parent span.
29
30    :type status: :class: `~opencensus.trace.status.Status`
31    :param status: (Optional) An optional final status for this span.
32
33    :type context_tracer: :class:`~opencensus.trace.tracers.noop_tracer.
34                                 NoopTracer`
35    :param context_tracer: The tracer that holds a stack of spans. If this is
36                           not None, then when exiting a span, use the end_span
37                           method in the tracer class to finish a span. If no
38                           tracer is passed in, then just finish the span using
39                           the finish method in the Span class.
40    """
41
42    def __init__(
43            self,
44            name=None,
45            parent_span=None,
46            attributes=None,
47            start_time=None,
48            end_time=None,
49            span_id=None,
50            stack_trace=None,
51            annotations=None,
52            message_events=None,
53            links=None,
54            status=None,
55            same_process_as_parent_span=None,
56            context_tracer=None,
57            span_kind=None):
58        self.name = name
59        self.parent_span = parent_span
60        self.start_time = start_time
61        self.end_time = end_time
62
63        self.span_id = generate_span_id()
64        self.parent_span = base.NullContextManager()
65
66        self.attributes = {}
67        self.stack_trace = stack_trace
68        self.annotations = annotations
69        self.message_events = message_events
70        self.links = []
71        self.status = status
72        self.same_process_as_parent_span = same_process_as_parent_span
73        self._child_spans = []
74        self.context_tracer = context_tracer
75        self.span_kind = span_kind
76
77    @staticmethod
78    def on_create(callback):
79        pass
80
81    @property
82    def children(self):
83        """The child spans of the current BlankSpan."""
84        return list()
85
86    def span(self, name='child_span'):
87        """Create a child span for the current span and append it to the child
88        spans list.
89
90        :type name: str
91        :param name: (Optional) The name of the child span.
92
93        :rtype: :class: `~opencensus.trace.blankspan.BlankSpan`
94        :returns: A child Span to be added to the current span.
95        """
96        child_span = BlankSpan(name, parent_span=self)
97        self._child_spans.append(child_span)
98        return child_span
99
100    def add_attribute(self, attribute_key, attribute_value):
101        """No-op implementation of this method.
102
103        :type attribute_key: str
104        :param attribute_key: Attribute key.
105
106        :type attribute_value:str
107        :param attribute_value: Attribute value.
108        """
109        pass
110
111    def add_annotation(self, description, **attrs):
112        """No-op implementation of this method.
113
114        :type description: str
115        :param description: A user-supplied message describing the event.
116                        The maximum length for the description is 256 bytes.
117
118        :type attrs: kwargs
119        :param attrs: keyworded arguments e.g. failed=True, name='Caching'
120        """
121        pass
122
123    def add_message_event(self, message_event):
124        """No-op implementation of this method.
125
126        :type message_event: :class:`opencensus.trace.time_event.MessageEvent`
127        :param message_event: The message event to attach to this span.
128        """
129        pass
130
131    def add_link(self, link):
132        """No-op implementation of this method.
133
134        :type link: :class: `~opencensus.trace.link.Link`
135        :param link: A Link object.
136        """
137        pass
138
139    def set_status(self, status):
140        """No-op implementation of this method.
141
142        :type code: :class: `~opencensus.trace.status.Status`
143        :param code: A Status object.
144        """
145        pass
146
147    def start(self):
148        """No-op implementation of this method."""
149        pass
150
151    def finish(self):
152        """No-op implementation of this method."""
153        pass
154
155    def __iter__(self):
156        """Iterate through the span tree."""
157        yield self
158
159    def __enter__(self):
160        """Start a span."""
161        return self
162
163    def __exit__(self, exception_type, exception_value, traceback):
164        """Finish a span."""
165        pass
166