1import abc
2import enum
3
4import six
5
6import grpc
7
8
9class ActiveSpanSource(six.with_metaclass(abc.ABCMeta)):
10    """Provides a way to access an the active span."""
11
12    @abc.abstractmethod
13    def get_active_span(self):
14        """Identifies the active span.
15
16    Returns:
17      An object that implements the opentracing.Span interface.
18    """
19        raise NotImplementedError()
20
21
22class RpcInfo(six.with_metaclass(abc.ABCMeta)):
23    """Provides information for an RPC call.
24
25  Attributes:
26    full_method: A string of the full RPC method, i.e., /package.service/method.
27    metadata: The initial :term:`metadata`.
28    timeout: The length of time in seconds to wait for the computation to
29      terminate or be cancelled.
30    request: The RPC request or None for request-streaming RPCs.
31    response: The RPC response or None for response-streaming or erroring RPCs.
32    error: The RPC error or None for successful RPCs.
33  """
34
35
36class SpanDecorator(six.with_metaclass(abc.ABCMeta)):
37    """Provides a mechanism to add arbitrary tags/logs/etc to the
38    opentracing.Span associated with client and/or server RPCs."""
39
40    @abc.abstractmethod
41    def __call__(self, span, rpc_info):
42        """Customizes an RPC span.
43
44    Args:
45      span: The client-side or server-side opentracing.Span for the RPC.
46      rpc_info: An RpcInfo describing the RPC.
47    """
48        raise NotImplementedError()
49
50
51def open_tracing_client_interceptor(tracer,
52                                    active_span_source=None,
53                                    log_payloads=False,
54                                    span_decorator=None):
55    """Creates an invocation-side interceptor that can be use with gRPC to add
56    OpenTracing information.
57
58  Args:
59    tracer: An object implmenting the opentracing.Tracer interface.
60    active_span_source: An optional ActiveSpanSource to customize how the
61      active span is determined.
62    log_payloads: Indicates whether requests should be logged.
63    span_decorator: An optional SpanDecorator.
64
65  Returns:
66    An invocation-side interceptor object.
67  """
68    from grpc_opentracing import _client
69    return _client.OpenTracingClientInterceptor(tracer, active_span_source,
70                                                log_payloads, span_decorator)
71
72
73def open_tracing_server_interceptor(tracer,
74                                    log_payloads=False,
75                                    span_decorator=None):
76    """Creates a service-side interceptor that can be use with gRPC to add
77    OpenTracing information.
78
79  Args:
80    tracer: An object implmenting the opentracing.Tracer interface.
81    log_payloads: Indicates whether requests should be logged.
82    span_decorator: An optional SpanDecorator.
83
84  Returns:
85    A service-side interceptor object.
86  """
87    from grpc_opentracing import _server
88    return _server.OpenTracingServerInterceptor(tracer, log_payloads,
89                                                span_decorator)
90
91
92###################################  __all__  #################################
93
94__all__ = ('ActiveSpanSource', 'RpcInfo', 'SpanDecorator',
95           'open_tracing_client_interceptor',
96           'open_tracing_server_interceptor',)
97