Initial version of Observer APIs

opentracing-observer/src/main/java/io/opentracing/contrib/observer/ExampleStatefulObserver.java

@@ -0,0 +1,75 @@
+/**
+ * Copyright 2017 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.opentracing.contrib.observer;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class ExampleStatefulObserver implements TracerObserver {
+
+    @Override
+    public SpanObserver onStart(SpanData spanData) {
+        return new StatefulSpanObserver(spanData);
+    }
+
+    public static class MyObserverState {
+        public MyObserverState() {
+        }
+    }
+
+    public static class StatefulSpanObserver implements SpanObserver {
+
+        private Map<Object,MyObserverState> spanState = new HashMap<Object,MyObserverState>();
+
+        public StatefulSpanObserver(SpanData spanData) {
+            MyObserverState state = new MyObserverState();
+            spanState.put(spanData.getSpanId(), state);
+        }
+
+        @Override
+        public void onSetOperationName(SpanData spanData, String operationName) {
+            // TODO Auto-generated method stub
+
+        }
+
+        @Override
+        public void onSetTag(SpanData spanData, String name, Object value) {
+            // TODO Auto-generated method stub
+
+        }
+
+        @Override
+        public void onSetBaggageItem(SpanData spanData, String key, String value) {
+            // TODO Auto-generated method stub
+
+        }
+
+        @Override
+        public void onLog(SpanData spanData, long timestampMicroseconds, Map<String, ?> fields) {
+            // TODO Auto-generated method stub
+
+        }
+
+        @Override
+        public void onLog(SpanData spanData, long timestampMicroseconds, String event) {
+            // TODO Auto-generated method stub
+
+        }
+
+        @Override
+        public void onFinish(SpanData spanData, long finishMicros) {
+            MyObserverState state = spanState.remove(spanData.getSpanId());
+        }
+    }
+}

opentracing-observer/src/main/java/io/opentracing/contrib/observer/ExampleStatelessObserver.java

@@ -0,0 +1,61 @@
+/**
+ * Copyright 2017 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.opentracing.contrib.observer;
+
+import java.util.Map;
+
+public class ExampleStatelessObserver implements TracerObserver, SpanObserver {
+
+    @Override
+    public SpanObserver onStart(SpanData spanData) {
+        return this;
+    }
+
+    @Override
+    public void onSetOperationName(SpanData spanData, String operationName) {
+        // TODO Auto-generated method stub
+
+    }
+
+    @Override
+    public void onSetTag(SpanData spanData, String name, Object value) {
+        // TODO Auto-generated method stub
+
+    }
+
+    @Override
+    public void onSetBaggageItem(SpanData spanData, String key, String value) {
+        // TODO Auto-generated method stub
+
+    }
+
+    @Override
+    public void onLog(SpanData spanData, long timestampMicroseconds, Map<String, ?> fields) {
+        // TODO Auto-generated method stub
+
+    }
+
+    @Override
+    public void onLog(SpanData spanData, long timestampMicroseconds, String event) {
+        // TODO Auto-generated method stub
+
+    }
+
+    @Override
+    public void onFinish(SpanData spanData, long finishMicros) {
+        // TODO Auto-generated method stub
+
+    }
+
+}

opentracing-observer/src/main/java/io/opentracing/contrib/observer/SpanData.java

@@ -0,0 +1,53 @@
+/**
+ * Copyright 2017 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.opentracing.contrib.observer;
+
+/**
+ * This interface provides information about the current {@link Span} to the observer
+ * methods.
+ *
+ */
+public interface SpanData {
+
+    /**
+     * This method returns an id that can be used for correlation purposes. It should only
+     * be used within the application to uniquely distinguish one span from another,
+     * to enable state to be maintained within observer implementation where appropriate.
+     *
+     * @return The unique id for the span
+     */
+    Object getSpanId();
+
+    /**
+     * The start time of the {@link Span}.
+     *
+     * @return The start time, in microseconds
+     */
+    long getStartTime();
+
+    String getOperationName();
+
+    /* Spec does not indicate that a tag key could have multiple values - but some tracers support
+     * this? Would be good to understand the usecase for multivalued keys - and add some text in the
+     * spec to clarify this?
+     * Possibly as well as returning the String,Boolean,Number values, it could return a List in those cases?
+     * 
+     * Q: Do we need a 'getTags' method - in which case would it return Map<String,List<?>> ?
+     * Other option may be to have a Set<String> getTagKeys() ?
+     */
+    Object getTag(String key);
+
+    Object getBaggageItem(String key);
+
+}

opentracing-observer/src/main/java/io/opentracing/contrib/observer/SpanObserver.java

@@ -0,0 +1,79 @@
+/**
+ * Copyright 2017 The OpenTracing Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.opentracing.contrib.observer;
+
+import java.util.Map;
+
+/**
+ * This interface represents an observer used to receive notifications related to a {@link Span}.
+ *
+ */
+public interface SpanObserver {
+
+    /**
+     * Notifies the observer that the operation name has been changed.
+     *
+     * @param spanData The data for the span
+     * @param operationName The new operation name
+     */
+    void onSetOperationName(SpanData spanData, String operationName);
+
+    /**
+     * Notifies the observer that the named tag has been set/changed.
+     *
+     * @param spanData The data for the span
+     * @param key The tag key
+     * @param value The tag value
+     */
+    void onSetTag(SpanData spanData, String key, Object value);
+
+    /**
+     * Notifies the observer that the named baggage item has been set/changed.
+     *
+     * @param spanData The data for the span
+     * @param key The baggage key
+     * @param value The baggage value
+     */
+    void onSetBaggageItem(SpanData spanData, String key, String value);
+
+    /**
+     * Notifies the observer that a log event has been recorded.
+     *
+     * @param spanData The data for the span
+     * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the
+     *                              Span's start timestamp.
+     * @param fields key:value log fields. Tracer implementations should support String, numeric, and boolean values;
+     *               some may also support arbitrary Objects.
+     */
+    void onLog(SpanData spanData, long timestampMicroseconds, Map<String, ?> fields);
+
+    /**
+     * Notifies the observer that a log event has been recorded.
+     *
+     * @param spanData The data for the span
+     * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the
+     *                              Span's start timestamp.
+     * @param event the event value; often a stable identifier for a moment in the Span lifecycle
+     */
+    void onLog(SpanData spanData, long timestampMicroseconds, String event);
+
+    /**
+     * Notifies the observer that the associated {@link Span} has finished.
+     *
+     * @param spanData The data for the span
+     * @param finishMicros The finish time in microseconds
+     */
+    void onFinish(SpanData spanData, long finishMicros);
+
+}

opentracing-observer/src/main/java/io/opentracing/contrib/observer/TracerObserver.java

@@ -13,10 +13,20 @@
  */
 package io.opentracing.contrib.observer;
 
+import io.opentracing.Span;
+
 /**
  * This interface represents an observer used to receive notifications related to {@link Span}s.
  *
  */
 public interface TracerObserver {
 
+    /**
+     * Notifies the observer that a new span has been started with the supplied data.
+     *
+     * @param spanData The data for the span being started
+     * @return The observer for the {@link Span}
+     */
+    SpanObserver onStart(SpanData spanData);
+
 }