diff --git a/examples/sdk-usage/README.md b/examples/sdk-usage/README.md new file mode 100644 index 0000000000..dac37f17e8 --- /dev/null +++ b/examples/sdk-usage/README.md @@ -0,0 +1,23 @@ +# SDK Usage Examples + +This is a simple example that demonstrates how to use and configure the OpenTelemetry SDK. + +## Prerequisites +* Java 1.8 or higher + + +## Compile +Compile with +```shell script +./gradlew fatJar +``` + +## Run + +The following commands are used to run the examples. +```shell script +java -cp build/libs/opentelemetry-example-sdk-usage-all-0.3.0-SNAPSHOT.jar io.opentelemetry.sdk.example.ConfigureTraceExample +``` +```shell script +java -cp build/libs/opentelemetry-example-sdk-usage-all-0.3.0-SNAPSHOT.jar io.opentelemetry.sdk.example.ConfigureSpanProcessorExample +``` \ No newline at end of file diff --git a/examples/sdk-usage/build.gradle b/examples/sdk-usage/build.gradle new file mode 100644 index 0000000000..d1b2a6772f --- /dev/null +++ b/examples/sdk-usage/build.gradle @@ -0,0 +1,37 @@ +plugins { + id 'java' + id 'com.github.sherter.google-java-format' version '0.8' + id "com.jfrog.artifactory" version "4.14.1" +} + +group 'io.opentelemetry' +version '0.3.0-SNAPSHOT' + + +//create a single Jar with all dependencies +task fatJar(type: Jar) { + baseName = project.name + '-all' + from { configurations.compile.collect { it.isDirectory() ? it : zipTree(it) } } + with jar +} + +googleJavaFormat { + toolVersion = '1.7' +} + +compileJava.dependsOn(verifyGoogleJavaFormat) + +repositories { + mavenCentral() + jcenter() + maven { + // Add snapshot repository + url "https://oss.jfrog.org/artifactory/oss-snapshot-local" + } +} + +dependencies { + compile "io.opentelemetry:opentelemetry-sdk:${version}" + compile "io.opentelemetry:opentelemetry-exporters-logging:${version}" + testCompile group: 'junit', name: 'junit', version: '4.12' +} \ No newline at end of file diff --git a/examples/sdk-usage/gradle/wrapper/gradle-wrapper.jar b/examples/sdk-usage/gradle/wrapper/gradle-wrapper.jar new file mode 100644 index 0000000000..87b738cbd0 Binary files /dev/null and b/examples/sdk-usage/gradle/wrapper/gradle-wrapper.jar differ diff --git a/examples/sdk-usage/gradle/wrapper/gradle-wrapper.properties b/examples/sdk-usage/gradle/wrapper/gradle-wrapper.properties new file mode 100644 index 0000000000..cc60ec7807 --- /dev/null +++ b/examples/sdk-usage/gradle/wrapper/gradle-wrapper.properties @@ -0,0 +1,6 @@ +#Fri Dec 06 12:31:29 CET 2019 +distributionUrl=https\://services.gradle.org/distributions/gradle-6.0.1-all.zip +distributionBase=GRADLE_USER_HOME +distributionPath=wrapper/dists +zipStorePath=wrapper/dists +zipStoreBase=GRADLE_USER_HOME diff --git a/examples/sdk-usage/gradlew b/examples/sdk-usage/gradlew new file mode 100755 index 0000000000..af6708ff22 --- /dev/null +++ b/examples/sdk-usage/gradlew @@ -0,0 +1,172 @@ +#!/usr/bin/env sh + +############################################################################## +## +## Gradle start up script for UN*X +## +############################################################################## + +# Attempt to set APP_HOME +# Resolve links: $0 may be a link +PRG="$0" +# Need this for relative symlinks. +while [ -h "$PRG" ] ; do + ls=`ls -ld "$PRG"` + link=`expr "$ls" : '.*-> \(.*\)$'` + if expr "$link" : '/.*' > /dev/null; then + PRG="$link" + else + PRG=`dirname "$PRG"`"/$link" + fi +done +SAVED="`pwd`" +cd "`dirname \"$PRG\"`/" >/dev/null +APP_HOME="`pwd -P`" +cd "$SAVED" >/dev/null + +APP_NAME="Gradle" +APP_BASE_NAME=`basename "$0"` + +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +DEFAULT_JVM_OPTS='"-Xmx64m"' + +# Use the maximum available, or set MAX_FD != -1 to use that value. +MAX_FD="maximum" + +warn () { + echo "$*" +} + +die () { + echo + echo "$*" + echo + exit 1 +} + +# OS specific support (must be 'true' or 'false'). +cygwin=false +msys=false +darwin=false +nonstop=false +case "`uname`" in + CYGWIN* ) + cygwin=true + ;; + Darwin* ) + darwin=true + ;; + MINGW* ) + msys=true + ;; + NONSTOP* ) + nonstop=true + ;; +esac + +CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar + +# Determine the Java command to use to start the JVM. +if [ -n "$JAVA_HOME" ] ; then + if [ -x "$JAVA_HOME/jre/sh/java" ] ; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD="$JAVA_HOME/jre/sh/java" + else + JAVACMD="$JAVA_HOME/bin/java" + fi + if [ ! -x "$JAVACMD" ] ; then + die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." + fi +else + JAVACMD="java" + which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." +fi + +# Increase the maximum file descriptors if we can. +if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then + MAX_FD_LIMIT=`ulimit -H -n` + if [ $? -eq 0 ] ; then + if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then + MAX_FD="$MAX_FD_LIMIT" + fi + ulimit -n $MAX_FD + if [ $? -ne 0 ] ; then + warn "Could not set maximum file descriptor limit: $MAX_FD" + fi + else + warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" + fi +fi + +# For Darwin, add options to specify how the application appears in the dock +if $darwin; then + GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" +fi + +# For Cygwin, switch paths to Windows format before running java +if $cygwin ; then + APP_HOME=`cygpath --path --mixed "$APP_HOME"` + CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` + JAVACMD=`cygpath --unix "$JAVACMD"` + + # We build the pattern for arguments to be converted via cygpath + ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` + SEP="" + for dir in $ROOTDIRSRAW ; do + ROOTDIRS="$ROOTDIRS$SEP$dir" + SEP="|" + done + OURCYGPATTERN="(^($ROOTDIRS))" + # Add a user-defined pattern to the cygpath arguments + if [ "$GRADLE_CYGPATTERN" != "" ] ; then + OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" + fi + # Now convert the arguments - kludge to limit ourselves to /bin/sh + i=0 + for arg in "$@" ; do + CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` + CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option + + if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition + eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` + else + eval `echo args$i`="\"$arg\"" + fi + i=$((i+1)) + done + case $i in + (0) set -- ;; + (1) set -- "$args0" ;; + (2) set -- "$args0" "$args1" ;; + (3) set -- "$args0" "$args1" "$args2" ;; + (4) set -- "$args0" "$args1" "$args2" "$args3" ;; + (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; + (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; + (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; + (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; + (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; + esac +fi + +# Escape application args +save () { + for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done + echo " " +} +APP_ARGS=$(save "$@") + +# Collect all arguments for the java command, following the shell quoting and substitution rules +eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" + +# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong +if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then + cd "$(dirname "$0")" +fi + +exec "$JAVACMD" "$@" diff --git a/examples/sdk-usage/gradlew.bat b/examples/sdk-usage/gradlew.bat new file mode 100644 index 0000000000..6d57edc706 --- /dev/null +++ b/examples/sdk-usage/gradlew.bat @@ -0,0 +1,84 @@ +@if "%DEBUG%" == "" @echo off +@rem ########################################################################## +@rem +@rem Gradle startup script for Windows +@rem +@rem ########################################################################## + +@rem Set local scope for the variables with windows NT shell +if "%OS%"=="Windows_NT" setlocal + +set DIRNAME=%~dp0 +if "%DIRNAME%" == "" set DIRNAME=. +set APP_BASE_NAME=%~n0 +set APP_HOME=%DIRNAME% + +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +set DEFAULT_JVM_OPTS="-Xmx64m" + +@rem Find java.exe +if defined JAVA_HOME goto findJavaFromJavaHome + +set JAVA_EXE=java.exe +%JAVA_EXE% -version >NUL 2>&1 +if "%ERRORLEVEL%" == "0" goto init + +echo. +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:findJavaFromJavaHome +set JAVA_HOME=%JAVA_HOME:"=% +set JAVA_EXE=%JAVA_HOME%/bin/java.exe + +if exist "%JAVA_EXE%" goto init + +echo. +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:init +@rem Get command-line arguments, handling Windows variants + +if not "%OS%" == "Windows_NT" goto win9xME_args + +:win9xME_args +@rem Slurp the command line arguments. +set CMD_LINE_ARGS= +set _SKIP=2 + +:win9xME_args_slurp +if "x%~1" == "x" goto execute + +set CMD_LINE_ARGS=%* + +:execute +@rem Setup the command line + +set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar + +@rem Execute Gradle +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS% + +:end +@rem End local scope for the variables with windows NT shell +if "%ERRORLEVEL%"=="0" goto mainEnd + +:fail +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of +rem the _cmd.exe /c_ return code! +if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 +exit /b 1 + +:mainEnd +if "%OS%"=="Windows_NT" endlocal + +:omega diff --git a/examples/sdk-usage/settings.gradle b/examples/sdk-usage/settings.gradle new file mode 100644 index 0000000000..edabe7fc5f --- /dev/null +++ b/examples/sdk-usage/settings.gradle @@ -0,0 +1,2 @@ +rootProject.name = 'opentelemetry-example-sdk-usage' + diff --git a/examples/sdk-usage/src/main/java/io/opentelemetry/sdk/example/ConfigureSpanProcessorExample.java b/examples/sdk-usage/src/main/java/io/opentelemetry/sdk/example/ConfigureSpanProcessorExample.java new file mode 100644 index 0000000000..955ea1290c --- /dev/null +++ b/examples/sdk-usage/src/main/java/io/opentelemetry/sdk/example/ConfigureSpanProcessorExample.java @@ -0,0 +1,90 @@ +/* + * Copyright 2020, OpenTelemetry 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.opentelemetry.sdk.example; + +import io.opentelemetry.exporters.logging.LoggingSpanExporter; +import io.opentelemetry.sdk.OpenTelemetrySdk; +import io.opentelemetry.sdk.trace.MultiSpanProcessor; +import io.opentelemetry.sdk.trace.SpanProcessor; +import io.opentelemetry.sdk.trace.TracerSdk; +import io.opentelemetry.sdk.trace.TracerSdkProvider; +import io.opentelemetry.sdk.trace.export.BatchSpansProcessor; +import io.opentelemetry.sdk.trace.export.SimpleSpansProcessor; +import java.util.Arrays; + +/** This example shows how to instantiate different Span Processors. */ +public class ConfigureSpanProcessorExample { + + static LoggingSpanExporter exporter = new LoggingSpanExporter(); + + // Get the Tracer Provider + static TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider(); + // Acquire a tracer + static TracerSdk tracer = tracerProvider.get("ConfigureSpanProcessorExample"); + + public static void main(String[] args) throws Exception { + + // Example how to configure the default SpanProcessors. + defaultSpanProcessors(); + // After this method, the following SpanProcessors are registered: + // - SimpleSpansProcessor + // - BatchSpansProcessor + // - MultiSpanProcessor <- this is a container for other SpanProcessors + // |-- SimpleSpansProcessor + // |-- BatchSpansProcessor + + // We generate a single Span so we can see some output on the console. + // Since there are 4 different SpanProcessor registered, this Span is exported 4 times. + tracer.spanBuilder("Span #1").startSpan().end(); + + // When exiting, it is recommended to call the shutdown method. This method calls `shutdown` on + // all configured SpanProcessors. This way, the configured exporters can release all resources + // and terminate their job sending the remaining traces to their back end. + tracerProvider.shutdown(); + } + + private static void defaultSpanProcessors() { + // OpenTelemetry offers 3 different default span processors: + // - SimpleSpanProcessor + // - BatchSpanProcessor + // - MultiSpanProcessor + // Default span processors require an exporter as parameter. In this example we use the + // LoggingSpanExporter which prints on the console output the spans. + + // Configure the simple spans processor. This span processor exports span immediately after they + // are ended. + SimpleSpansProcessor simpleSpansProcessor = SimpleSpansProcessor.newBuilder(exporter).build(); + tracerProvider.addSpanProcessor(simpleSpansProcessor); + + // Configure the batch spans processor. This span processor exports span in batches. + BatchSpansProcessor batchSpansProcessor = + BatchSpansProcessor.newBuilder(exporter) + .reportOnlySampled(true) // send to the exporter only spans that have been sampled + .setMaxExportBatchSize(512) // set the maximum batch size to use + .setMaxQueueSize(2048) // set the queue size. This must be >= the export batch size + .setExporterTimeoutMillis( + 30_000) // set the max amount of time an export can run before getting interrupted + .setScheduleDelayMillis(5000) // set time between two different exports + .build(); + tracerProvider.addSpanProcessor(batchSpansProcessor); + + // Configure the multi spans processor. A MultiSpanProcessor accepts a list of Span Processors. + SpanProcessor multiSpanProcessor = + MultiSpanProcessor.create(Arrays.asList(simpleSpansProcessor, batchSpansProcessor)); + tracerProvider.addSpanProcessor(multiSpanProcessor); + } +} diff --git a/examples/sdk-usage/src/main/java/io/opentelemetry/sdk/example/ConfigureTraceExample.java b/examples/sdk-usage/src/main/java/io/opentelemetry/sdk/example/ConfigureTraceExample.java new file mode 100644 index 0000000000..37e7a9b4b8 --- /dev/null +++ b/examples/sdk-usage/src/main/java/io/opentelemetry/sdk/example/ConfigureTraceExample.java @@ -0,0 +1,184 @@ +/* + * Copyright 2020, OpenTelemetry 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.opentelemetry.sdk.example; + +import io.opentelemetry.common.AttributeValue; +import io.opentelemetry.exporters.logging.LoggingSpanExporter; +import io.opentelemetry.sdk.OpenTelemetrySdk; +import io.opentelemetry.sdk.trace.Sampler; +import io.opentelemetry.sdk.trace.Samplers; +import io.opentelemetry.sdk.trace.TracerSdk; +import io.opentelemetry.sdk.trace.TracerSdkProvider; +import io.opentelemetry.sdk.trace.config.TraceConfig; +import io.opentelemetry.sdk.trace.export.SimpleSpansProcessor; +import io.opentelemetry.trace.Link; +import io.opentelemetry.trace.Span; +import io.opentelemetry.trace.SpanContext; +import io.opentelemetry.trace.SpanId; +import io.opentelemetry.trace.TraceId; +import java.util.Collections; +import java.util.List; +import java.util.Map; + +class ConfigureTraceExample { + + // Configure a tracer for these examples + static TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider(); + static TracerSdk tracer = tracerProvider.get("ConfigureTraceExample"); + + static { + tracerProvider.addSpanProcessor( + SimpleSpansProcessor.newBuilder(new LoggingSpanExporter()).build()); + } + + public static void main(String[] args) { + + // TraceConfig handles the global tracing configuration + printTraceConfig(); + + // OpenTelemetry has a maximum of 32 Attributes by default for Spans, Links, and Events. + Span multiAttrSpan = tracer.spanBuilder("Example Span Attributes").startSpan(); + multiAttrSpan.setAttribute("Attribute 1", "first attribute value"); + multiAttrSpan.setAttribute("Attribute 2", "second attribute value"); + multiAttrSpan.end(); + + // The configuration can be changed in the trace provider. + // For example, we can change the maximum number of Attributes per span to 1. + TraceConfig newConf = + tracerProvider.getActiveTraceConfig().toBuilder().setMaxNumberOfAttributes(1).build(); + tracerProvider.updateActiveTraceConfig(newConf); + printTraceConfig(); + + // If more attributes than allowed by the configuration are set, they are dropped. + Span singleAttrSpan = tracer.spanBuilder("Example Span Attributes").startSpan(); + singleAttrSpan.setAttribute("Attribute 1", "first attribute value"); + singleAttrSpan.setAttribute("Attribute 2", "second attribute value"); + singleAttrSpan.end(); + + // OpenTelemetry offers three different default samplers: + // - alwaysOn: it samples all traces + // - alwaysOff: it rejects all traces + // - probability: it samples traces based on the probability passed in input + TraceConfig alwaysOff = + tracerProvider.getActiveTraceConfig().toBuilder().setSampler(Samplers.alwaysOff()).build(); + TraceConfig alwaysOn = + tracerProvider.getActiveTraceConfig().toBuilder().setSampler(Samplers.alwaysOn()).build(); + TraceConfig probability = + tracerProvider + .getActiveTraceConfig() + .toBuilder() + .setSampler(Samplers.probability(0.5)) + .build(); + + // We update the configuration to use the alwaysOff sampler. + tracerProvider.updateActiveTraceConfig(alwaysOff); + printTraceConfig(); + tracer.spanBuilder("Not forwarded to any processors").startSpan().end(); + tracer.spanBuilder("Not forwarded to any processors").startSpan().end(); + + // We update the configuration to use the alwaysOn sampler. + tracerProvider.updateActiveTraceConfig(alwaysOn); + printTraceConfig(); + tracer.spanBuilder("Forwarded to all processors").startSpan().end(); + tracer.spanBuilder("Forwarded to all processors").startSpan().end(); + + // We update the configuration to use the probability sampler which was configured to sample + // only 50% of the spans. + tracerProvider.updateActiveTraceConfig(probability); + printTraceConfig(); + for (int i = 0; i < 10; i++) { + tracer + .spanBuilder(String.format("Span %d might be forwarded to all processors", i)) + .startSpan() + .end(); + } + + // We can also implement our own sampler. We need to implement the + // io.opentelemetry.sdk.trace.Sampler interface. + class MySampler implements Sampler { + + @Override + public Decision shouldSample( + SpanContext parentContext, + TraceId traceId, + SpanId spanId, + String name, + Span.Kind spanKind, + Map attributes, + List parentLinks) { + // We sample only if the Span name contains "SAMPLE" + return new Decision() { + + @Override + public boolean isSampled() { + return name.contains("SAMPLE"); + } + + @Override + public Map attributes() { + // This method MUST return an immutable list of Attributes + // that will be added to the generated Span. + return Collections.emptyMap(); + } + }; + } + + @Override + public String getDescription() { + return "My Sampler Implementation!"; + } + } + + // Add MySampler to the Trace Configuration + TraceConfig mySampler = + tracerProvider.getActiveTraceConfig().toBuilder().setSampler(new MySampler()).build(); + tracerProvider.updateActiveTraceConfig(mySampler); + printTraceConfig(); + + tracer.spanBuilder("#1 - SamPleD").startSpan().end(); + tracer + .spanBuilder("#2 - SAMPLE this trace will be the first to be printed in the console output") + .startSpan() + .end(); + tracer.spanBuilder("#3 - Smth").startSpan().end(); + tracer + .spanBuilder("#4 - SAMPLED this trace will be the second one shown in the console output") + .startSpan() + .end(); + tracer.spanBuilder("#5").startSpan().end(); + + // Example's over! We can release the resources of OpenTelemetry calling the shutdown method. + OpenTelemetrySdk.getTracerProvider().shutdown(); + } + + private static void printTraceConfig() { + TraceConfig config = tracerProvider.getActiveTraceConfig(); + System.err.println("=================================="); + System.err.print("Max number of attributes: "); + System.err.println(config.getMaxNumberOfAttributes()); + System.err.print("Max number of attributes per event: "); + System.err.println(config.getMaxNumberOfAttributesPerEvent()); + System.err.print("Max number of attributes per link: "); + System.err.println(config.getMaxNumberOfAttributesPerLink()); + System.err.print("Max number of events: "); + System.err.println(config.getMaxNumberOfEvents()); + System.err.print("Max number of links: "); + System.err.println(config.getMaxNumberOfLinks()); + System.err.print("Sampler: "); + System.err.println(config.getSampler().getDescription()); + } +}