Skip to content

Doc update tracing #5632

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
samvaity merged 8 commits into from
Oct 3, 2019
Merged

Doc update tracing #5632

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
4935d71
add tests and docs
samvaity Sep 30, 2019
b296dd4
move process kind to util tracing
samvaity Oct 1, 2019
865383e
fixing spotbugs
samvaity Oct 1, 2019
9464a12
code snippet changes
samvaity Oct 2, 2019
b0d58b0
fix checkstyle
samvaity Oct 2, 2019
67212e2
review comments
samvaity Oct 2, 2019
d96bea2
update changelog
samvaity Oct 2, 2019
25d31d1
add paragraph tags
samvaity Oct 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...core/azure-core-amqp/src/main/java/com/azure/core/amqp/implementation/TracerProvider.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
package com.azure.core.amqp.implementation;

import com.azure.core.amqp.exception.AmqpException;
import com.azure.core.implementation.tracing.ProcessKind;
import com.azure.core.util.tracing.ProcessKind;
import com.azure.core.util.Context;
import com.azure.core.util.logging.ClientLogger;
import com.azure.core.util.tracing.Tracer;
Expand Down
2 changes: 1 addition & 1 deletion .../azure-core-amqp/src/test/java/com/azure/core/amqp/implementation/TracerProviderTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

import com.azure.core.amqp.exception.AmqpException;
import com.azure.core.amqp.exception.ErrorCondition;
import com.azure.core.implementation.tracing.ProcessKind;
import com.azure.core.util.tracing.ProcessKind;
import com.azure.core.util.Context;
import com.azure.core.util.tracing.Tracer;
import org.junit.After;
Expand Down
2 changes: 1 addition & 1 deletion ...e/implementation/tracing/ProcessKind.java → .../azure/core/util/tracing/ProcessKind.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.core.implementation.tracing;
package com.azure.core.util.tracing;

/**
* Contains constants common AMQP protocol process calls.
Expand Down
148 changes: 92 additions & 56 deletions sdk/core/azure-core/src/main/java/com/azure/core/util/tracing/Tracer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,31 @@

package com.azure.core.util.tracing;

import com.azure.core.implementation.tracing.ProcessKind;
import com.azure.core.util.Context;

/**
* Contract that all tracers must implement to be plug-able into the SDK.
*
*/
public interface Tracer {
/**
* Key for {@link Context} which indicates that the context contains OpenCensus span data. This span will be used
* as the parent span for all spans the SDK creates.
*
* If no span data is listed when the SDK creates its first span it will be used as the parent for all further spans
* it creates.
* <p>
* If no span data is listed when the SDK creates its first span, this span key will be used as the parent span.
*/
String OPENCENSUS_SPAN_KEY = "opencensus-span";

/**
* Key for {@link Context} which indicates that the context contains the name for the OpenCensus spans that are
* created.
*
* <p>
* If no span name is listed when the span is created it will default to using the calling method's name.
*/
String OPENCENSUS_SPAN_NAME_KEY = "opencensus-span-name";

/**
* Key for {@link Context} which indicates that the context contains the Entity Path, remote endpoint path.
*
* Key for {@link Context} which indicates that the context contains an entity path.
*/
String ENTITY_PATH = "entity-path";

Expand All @@ -40,61 +38,108 @@ public interface Tracer {
String HOST_NAME = "hostname";

/**
* Key for {@link Context} which indicates that the context contains message Span Context.
* Key for {@link Context} which indicates that the context contains a message span context.
*
*/
String SPAN_CONTEXT = "span-context";

/**
* Key for {@link Context} which indicates that the context contains the Diagnostic Id for the service call.
* Key for {@link Context} which indicates that the context contains a "Diagnostic Id" for the service call.
*
*/
String DIAGNOSTIC_ID_KEY = "diagnostic-id";

/**
* Creates a new tracing span.
* <p>
* The {@code context} will be checked for containing information about a parent span. If a parent span is found,
* the new span will be added as a child. Otherwise the parent span will be created and added to the {@code context}
* and any downstream {@code start()} calls will use the created span as the parent.
*
* The {@code context} will be checked for containing information about a parent span. If a parent span is found the
* new span will be added as a child, otherwise the span will be created and added to the context and any downstream
* start calls will use the created span as the parent.
* <p><strong>Code samples</strong></p>
*
* <p>Starts a tracing span with provided method name and explicit parent span</p>
* {@codesnippet com.azure.core.util.tracing.start#string-context}
*
* @param methodName Name of the method triggering the span creation.
* @param context Additional metadata that is passed through the call stack.
* @return An updated context object.
*
* @return The updated {@link Context} object containing the returned span.
* @throws NullPointerException if {@code methodName} or {@code context} is {@code null}.
*/
Context start(String methodName, Context context);

/**
* Creates a new tracing span.
* Creates a new tracing span for AMQP calls.
*
* <p>
* The {@code context} will be checked for containing information about a parent span. If a parent span is found the
* new span will be added as a child, otherwise the span will be created and added to the context and any downstream
* start calls will use the created span as the parent.
* new span will be added as a child. Otherwise the span will be created and added to the {@code context} and any
* downstream {@code start()} calls will use the created span as the parent.
*
* <p>
* Sets additional request attributes on the created span when {@code processKind} is
* {@link ProcessKind#SEND ProcessKind.SEND}.
*
* <p>
* Returns the diagnostic Id and span context of the returned span when {@code processKind} is
* {@link ProcessKind#RECEIVE ProcessKind.RECEIVE}.
*
* <p>
* Creates a new tracing span with remote parent and returns that scope when the given when {@code processKind}
* is {@link ProcessKind#PROCESS ProcessKind.PROCESS}.
*
* <p><strong>Code samples</strong></p>
*
* <p>Starts a tracing span with provided method name and AMQP operation SEND</p>
* {@codesnippet com.azure.core.util.tracing.start#string-context-processKind-SEND}
*
* <p>Starts a tracing span with provided method name and AMQP operation RECEIVE</p>
* {@codesnippet com.azure.core.util.tracing.start#string-context-processKind-RECEIVE}
*
* <p>Starts a tracing span with provided method name and AMQP operation PROCESS</p>
* {@codesnippet com.azure.core.util.tracing.start#string-context-processKind-PROCESS}
*
* @param methodName Name of the method triggering the span creation.
* @param context Additional metadata that is passed through the call stack.
* @param processKind AMQP message process kind.
* @return An updated context object.
* @param processKind AMQP operation kind.
*
* @return The updated {@link Context} object containing the returned span.
* @throws NullPointerException if {@code methodName} or {@code context} or {@code processKind} is {@code null}.
*/
Context start(String methodName, Context context, ProcessKind processKind);

/**
* Completes the current tracing span.
*
* <p><strong>Code samples</strong></p>
*
* <p>Completes the tracing span present in the context, with the corresponding OpenCensus status for the given
* response status code</p>
* {@codesnippet com.azure.core.util.tracing.end#int-throwable-context}
*
* @param responseCode Response status code if the span is in a HTTP call context.
* @param error Potential throwable that happened during the span.
* @param error {@link Throwable} that happened during the span or {@code null} if no exception occurred.
* @param context Additional metadata that is passed through the call stack.
* @throws NullPointerException if {@code context} is {@code null}.
*/
void end(int responseCode, Throwable error, Context context);

/**
* Completes the current tracing span.
*
* @param errorCondition the error message that occurred during the call.
* @param error Potential throwable that happened during the span.
* <p><strong>Code samples</strong></p>
*
* <p>Completes the tracing span with the corresponding OpenCensus status for the given status message</p>
* {@codesnippet com.azure.core.util.tracing.end#string-throwable-context}
*
* @param statusMessage the error or success message that occurred during the call, or {@code null} if no error
* occurred.
* @param error {@link Throwable} that happened during the span or {@code null} if no exception occurred.
* @param context Additional metadata that is passed through the call stack.
* @throws NullPointerException if {@code context} is {@code null}.
*/
void end(String errorCondition, Throwable error, Context context);
void end(String statusMessage, Throwable error, Context context);

/**
* Adds metadata to the current span. The {@code context} is checked for having span information, if no span
Expand All @@ -103,62 +148,53 @@ public interface Tracer {
* @param key Name of the metadata.
* @param value Value of the metadata.
* @param context Additional metadata that is passed through the call stack.
* @throws NullPointerException if {@code key} or {@code value} or {@code context} is {@code null}.
*/
void setAttribute(String key, String value, Context context);

/*
* Adds metadata to the current span. The {@code context} is checked for having span information, if no span
* information is found in the context no metadata is added.
*
* @param key Name of the metadata.
* @param value Value of the metadata.
* @param context Additional metadata that is passed through the call stack.
*/
// void setAttribute(String key, long value, Context context);

/*
* Adds metadata to the current span. The {@code context} is checked for having span information, if no span
* information is found in the context no metadata is added.
/**
* Sets the name for spans that are created.
*
* @param key Name of the metadata.
* @param value Value of the metadata.
* @param context Additional metadata that is passed through the call stack.
*/
// void setAttribute(String key, double value, Context context);

/*
* Adds metadata to the current span. The {@code context} is checked for having span information, if no span
* information is found in the context no metadata is added.
* <p><strong>Code samples</strong></p>
*
* @param key Name of the metadata.
* @param value Value of the metadata.
* @param context Additional metadata that is passed through the call stack.
*/
// void setAttribute(String key, boolean value, Context context);

/**
* Configures the name for spans that are created.
* <p>Retrieve the span name of the returned span</p>
* {@codesnippet com.azure.core.util.tracing.setSpanName#string-context}
*
* @param spanName Name to give the next span.
* @param context Additional metadata that is passed through the call stack.
* @return An updated context object.
*
* @return The updated {@link Context} object containing the name of the returned span.
* @throws NullPointerException if {@code spanName} or {@code context} is {@code null}.
*/
Context setSpanName(String spanName, Context context);

/**
* Adds a link to the tracing span.
* Provides a way to link multiple tracing spans.
* Used in batching operations to relate multiple requests under a single batch.
*
* <p><strong>Code samples</strong></p>
*
* <p>Link multiple spans using their span context information</p>
* {@codesnippet com.azure.core.util.tracing.addLink#context}
*
* @param context Additional metadata that is passed through the call stack.
* @throws NullPointerException if {@code context} is {@code null}.
*/
void addLink(Context context);

/**
* Extracts the span's {@link Context} from the given event's diagnostic id.
* Extracts the span's context as {@link Context} from upstream.
*
* <p><strong>Code samples</strong></p>
*
* <p>Extracts the corresponding span context information from a valid diagnostic id</p>
* {@codesnippet com.azure.core.util.tracing.extractContext#string-context}
*
* @param diagnosticId Unique identifier for the trace information of the span.
* @param context Additional metadata that is passed through the call stack.
* @return An updated context object.
*
* @return The updated {@link Context} object containing the span context.
* @throws NullPointerException if {@code diagnosticId} or {@code context} is {@code null}.
*/
Context extractContext(String diagnosticId, Context context);
}
15 changes: 0 additions & 15 deletions sdk/core/azure-core/src/main/java/module-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,21 +107,6 @@
com.azure.storage.blob, // FIXME this should not be a long-term solution
com.azure.storage.file, // FIXME this should not be a long-term solution
com.azure.storage.queue; // FIXME this should not be a long-term solution
exports com.azure.core.implementation.tracing to
com.azure.core.management, // FIXME this should not be a long-term solution
com.azure.core.test, // FIXME this should not be a long-term solution
com.azure.core.amqp, // FIXME this should not be a long-term solution
com.azure.http.netty, // FIXME this should not be a long-term solution
com.azure.messaging.eventhubs, // FIXME this should not be a long-term solution
com.azure.messaging.eventhubs.checkpointstore.blob, // FIXME this should not be a long-term solution
com.azure.identity, // FIXME this should not be a long-term solution
com.azure.security.keyvault.keys, // FIXME this should not be a long-term solution
com.azure.security.keyvault.secrets, // FIXME this should not be a long-term solution
com.azure.storage.common, // FIXME this should not be a long-term solution
com.azure.core.tracing.opencensus, // FIXME this should not be a long-term solution
com.azure.storage.blob, // FIXME this should not be a long-term solution
com.azure.storage.file, // FIXME this should not be a long-term solution
com.azure.storage.queue; // FIXME this should not be a long-term solution
exports com.azure.core.implementation.exception to
com.azure.core.management, // FIXME this should not be a long-term solution
com.azure.core.test, // FIXME this should not be a long-term solution
Expand Down
Loading