Add http example (#695)

* Add build scripts for HTTP example

Add HTTP example

Improved naming and formatting

Add Semantic Convention to traces

Fix semantic convention

* Add Examples as OpenTelementry project

* Changed the build configuration - Examples are compiled with the main project

* Addressing comment of @carlosalberto

* Addressed the feedback of @bogdandrutu

* Removed InMemory exporter. Example as standalone project.

* Remove examples from main build

* Making the exporter private and static

Change visibility of attributes

* Update HTTP example README

* Apply java format

Co-authored-by: Inseo Kim <sano307@naver.com>
This commit is contained in:
Giovanni Liva 2020-03-24 17:08:52 +01:00 committed by GitHub
parent 465664cddc
commit 2d892444d1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 615 additions and 0 deletions

30
examples/http/README.md Normal file
View File

@ -0,0 +1,30 @@
# HTTP Example
**Note:** This is an advanced scenario useful for people that want to *manually* instrument their own code.
This is a simple example that demonstrates how to use the OpenTelemetry SDK
to *manually* instrument a simple HTTP based Client/Server application.
The example creates the **Root Span** on the client and sends the context
over the HTTP request. On the server side, the example shows how to extract the context
and create a **Child Span** with attached a **Span Event**.
# How to run
## Prerequisites
* Java 1.8.231
* Be on the project root folder
## 1 - Compile
```bash
gradlew fatJar
```
## 2 - Start the Server
```bash
java -cp ./build/libs/opentelemetry-example-http-all-0.2.0.jar io.opentelemetry.example.http.HttpServer
```
## 3 - Start the Client
```bash
java -cp ./build/libs/opentelemetry-example-http-all-0.2.0.jar io.opentelemetry.example.http.HttpClient
```

View File

@ -0,0 +1,26 @@
plugins {
id 'java'
}
group 'io.opentelemetry'
version '0.2.0'
//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
}
repositories {
mavenCentral()
}
dependencies {
compile('io.opentelemetry:opentelemetry-api:0.2.0')
compile('io.opentelemetry:opentelemetry-sdk:0.2.0')
compile('io.opentelemetry:opentelemetry-exporters-logging:0.2.0')
compile('io.grpc:grpc-protobuf:1.24.0')
compile('io.grpc:grpc-netty-shaded:1.24.0')
testCompile group: 'junit', name: 'junit', version: '4.12'
}

Binary file not shown.

View File

@ -0,0 +1,6 @@
#Fri Dec 06 12:31:29 CET 2019
distributionUrl=https\://services.gradle.org/distributions/gradle-5.2.1-all.zip
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStorePath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME

172
examples/http/gradlew vendored Executable file
View File

@ -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" "$@"

84
examples/http/gradlew.bat vendored Normal file
View File

@ -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

View File

@ -0,0 +1,2 @@
rootProject.name = 'opentelemetry-example-http'

View File

@ -0,0 +1,135 @@
/*
* Copyright 2019, 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.example.http;
import io.opentelemetry.OpenTelemetry;
import io.opentelemetry.context.propagation.HttpTextFormat;
import io.opentelemetry.exporters.logging.LoggingExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.TracerSdkFactory;
import io.opentelemetry.sdk.trace.export.SimpleSpansProcessor;
import io.opentelemetry.trace.Span;
import io.opentelemetry.trace.Status;
import io.opentelemetry.trace.Tracer;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.Charset;
public class HttpClient {
// OTel API
private static Tracer tracer =
OpenTelemetry.getTracerFactory().get("io.opentelemetry.example.http.HttpClient");
// Export traces to log
private static LoggingExporter loggingExporter = new LoggingExporter();
// Inject the span context into the request
private static HttpTextFormat.Setter<HttpURLConnection> setter =
new HttpTextFormat.Setter<HttpURLConnection>() {
@Override
public void put(HttpURLConnection carrier, String key, String value) {
carrier.setRequestProperty(key, value);
}
};
private void initTracer() {
// Get the tracer
TracerSdkFactory tracerFactory = OpenTelemetrySdk.getTracerFactory();
// Show that multiple exporters can be used
// Set to export the traces also to a log file
tracerFactory.addSpanProcessor(SimpleSpansProcessor.newBuilder(loggingExporter).build());
}
private HttpClient() throws Exception {
initTracer();
// Connect to the server locally
int port = 8080;
URL url = new URL("http://127.0.0.1:" + port);
HttpURLConnection con = (HttpURLConnection) url.openConnection();
// Name convention for the Span is not yet defined.
// See: https://github.com/open-telemetry/opentelemetry-specification/issues/270
Span span = tracer.spanBuilder("/").setSpanKind(Span.Kind.CLIENT).startSpan();
// TODO provide semantic convention attributes to Span.Builder
span.setAttribute("component", "http");
span.setAttribute("http.method", "GET");
/*
Only one of the following is required:
- http.url
- http.scheme, http.host, http.target
- http.scheme, peer.hostname, peer.port, http.target
- http.scheme, peer.ip, peer.port, http.target
*/
span.setAttribute("http.url", url.toString());
// Inject the request with the context
tracer.getHttpTextFormat().inject(span.getContext(), con, setter);
StringBuilder content = new StringBuilder();
int status = 0;
try {
// Process the request
con.setRequestMethod("GET");
status = con.getResponseCode();
BufferedReader in =
new BufferedReader(new InputStreamReader(con.getInputStream(), Charset.defaultCharset()));
String inputLine;
while ((inputLine = in.readLine()) != null) {
content.append(inputLine);
}
in.close();
// Close the Span
span.setStatus(Status.OK);
} catch (Exception e) {
// TODO create mapping for Http Error Codes <-> io.opentelemetry.trace.Status
span.setStatus(Status.UNKNOWN.withDescription("HTTP Code: " + status));
}
span.end();
// Output the result of the request
System.out.println("Response Code: " + status);
System.out.println("Response Msg: " + content);
}
/**
* Main method to run the example.
*
* @param args It is not required.
*/
public static void main(String[] args) {
// Perform request every 5s
Thread t =
new Thread() {
@Override
public void run() {
while (true) {
try {
HttpClient c = new HttpClient();
Thread.sleep(5000);
} catch (Exception e) {
System.out.println(e.getMessage());
}
}
}
};
t.start();
}
}

View File

@ -0,0 +1,160 @@
/*
* Copyright 2019, 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.example.http;
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpHandler;
import io.opentelemetry.OpenTelemetry;
import io.opentelemetry.context.propagation.HttpTextFormat;
import io.opentelemetry.exporters.logging.LoggingExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.TracerSdkFactory;
import io.opentelemetry.sdk.trace.export.SimpleSpansProcessor;
import io.opentelemetry.trace.*;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.nio.charset.Charset;
import java.util.HashMap;
import java.util.Map;
public class HttpServer {
private class HelloHandler implements HttpHandler {
@Override
public void handle(HttpExchange he) throws IOException {
// Name convention for the Span is not yet defined.
// See: https://github.com/open-telemetry/opentelemetry-specification/issues/270
Span.Builder spanBuilder = tracer.spanBuilder("/").setSpanKind(Span.Kind.SERVER);
Span span = null;
try {
// Extract the context from the HTTP request
SpanContext ctx = tracer.getHttpTextFormat().extract(he, getter);
// Rebuild a span with the received context
span = spanBuilder.setParent(ctx).startSpan();
} catch (StringIndexOutOfBoundsException e) {
// msg without ctx
span = spanBuilder.startSpan();
}
// Set the Semantic Convention
span.setAttribute("component", "http");
span.setAttribute("http.method", "GET");
/*
One of the following is required:
- http.scheme, http.host, http.target
- http.scheme, http.server_name, net.host.port, http.target
- http.scheme, net.host.name, net.host.port, http.target
- http.url
*/
span.setAttribute("http.scheme", "http");
span.setAttribute("http.host", "localhost:" + HttpServer.port);
span.setAttribute("http.target", "/");
// Process the request
answer(he, span);
// Close the span
span.end();
}
private void answer(HttpExchange he, Span span) throws IOException {
// Generate an Event
span.addEvent("Start Processing");
// Process the request
String response = "Hello World!";
he.sendResponseHeaders(200, response.length());
OutputStream os = he.getResponseBody();
os.write(response.getBytes(Charset.defaultCharset()));
os.close();
System.out.println("Served Client: " + he.getRemoteAddress());
// Generate an Event with an attribute
Map<String, AttributeValue> event = new HashMap<>();
event.put("answer", AttributeValue.stringAttributeValue(response));
span.addEvent("Finish Processing", event);
// Everything works fine in this example
span.setStatus(Status.OK);
}
}
private com.sun.net.httpserver.HttpServer server;
private static int port = 8080;
// OTel API
private static Tracer tracer =
OpenTelemetry.getTracerFactory().get("io.opentelemetry.example.http.HttpServer");
// Export traces to log
private static LoggingExporter loggingExporter = new LoggingExporter();
// Extract the context from http headers
private static HttpTextFormat.Getter<HttpExchange> getter =
new HttpTextFormat.Getter<HttpExchange>() {
@Override
public String get(HttpExchange carrier, String key) {
if (carrier.getRequestHeaders().containsKey(key)) {
return carrier.getRequestHeaders().get(key).get(0);
}
return "";
}
};
private HttpServer() throws IOException {
this(port);
}
private HttpServer(int port) throws IOException {
initTracer();
server = com.sun.net.httpserver.HttpServer.create(new InetSocketAddress(port), 0);
// Test urls
server.createContext("/", new HelloHandler());
server.start();
System.out.println("Server ready on http://127.0.0.1:" + port);
}
private void initTracer() {
// Get the tracer
TracerSdkFactory tracerFactory = OpenTelemetrySdk.getTracerFactory();
// Show that multiple exporters can be used
// Set to export the traces also to a log file
tracerFactory.addSpanProcessor(SimpleSpansProcessor.newBuilder(loggingExporter).build());
}
private void stop() {
server.stop(0);
}
/**
* Main method to run the example.
*
* @param args It is not required.
* @throws Exception Something might go wrong.
*/
public static void main(String[] args) throws Exception {
final HttpServer s = new HttpServer();
// Gracefully close the server
Runtime.getRuntime()
.addShutdownHook(
new Thread() {
@Override
public void run() {
s.stop();
}
});
}
}