Skip to content

Commit 20f5063

Browse files
jasonjkellerjwatson
authored andcommitted
Initial Release Commit
0 parents  commit 20f5063

17 files changed

+1409
-0
lines changed

.gitignore

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
bin/
2+
build/
3+
out/
4+
reports/
5+
out/
6+
.classpath
7+
.project
8+
.settings
9+
.gradle
10+
.metadata
11+
derbyDB
12+
pyvenv.cfg
13+
test_database*
14+
*.log
15+
.emacs.*
16+
.lock
17+
.cache-main
18+
19+
.DS_Store
20+
*.iws
21+
*.ipr
22+
*.iml
23+
/out/
24+
/.settings/
25+
.idea
26+
.shelf
27+
28+
.recommenders
29+
production/
30+
31+

README.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# AWS Lambda OpenTracing Java SDK
2+
3+
## Purpose
4+
5+
Open Tracing instrumentation for AWS Lambda [RequestHandler](https://github.com/aws/aws-lambda-java-libs/blob/master/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java) and [RequestStreamHandler](https://github.com/aws/aws-lambda-java-libs/blob/master/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestStreamHandler.java).
6+
7+
## How it Works
8+
9+
The SDK provides `TracingRequestHandler` and `TracingRequestStreamHandler` interfaces that extend AWS' Lambda request handlers. When a Lambda function that is using an implementation of either tracing request handler is invoked, the handler will obtain the globally registered OpenTracing [Tracer](https://opentracing.io/docs/overview/tracers/) and create/start an OpenTracing [Span](https://opentracing.io/docs/overview/spans/) to capture timing information and `key:value` pairs ([Tags/Logs](https://opentracing.io/docs/overview/tags-logs-baggage/)) detailing the trace data.
10+
11+
As part of the implementation the user must override the tracing handler's `doHandleRequest` method which is called by the handler interface's `handleRequest` method.
12+
13+
## Collected Span Tags/Logs
14+
15+
Lambda attributes:
16+
17+
| Tag key | Tag type | Note |
18+
| :------------------------------: | :-------: | :---------------------------------------------------------------: |
19+
| `aws.requestId` | `String` | AWS Request ID is a unique GUID assigned to each invocation |
20+
| `aws.lambda.arn` | `String` | ARN of the current Lambda function |
21+
| `aws.lambda.eventSource.arn` | `String` | ARN of the invocation source |
22+
| `aws.lambda.coldStart` | `boolean` | Indicates if Lambda invocation was a cold start, omitted if false |
23+
24+
Exception log:
25+
26+
| Log key | Log type | Note |
27+
| :------------: | :---------------------: | :----------------------------------------------: |
28+
| `event` | `String` `"error"` | Indicates that an error event has occurred |
29+
| `error.object` | `Throwable` | The `Throwable` object |
30+
| `message` | `Throwable` message | The detail message string of the throwable |
31+
| `stack` | `Throwable` stacktrace | The the stack trace information of the throwable |
32+
| `error.kind` | `String` `"Exception"` | Indicates that the error was an `Exception` |
33+
34+
## How to Use
35+
36+
1. Add the `java-aws-lambda` dependency to your project.
37+
- **Option A:** [Build the project from sources](#build-the-project) and [add the jar to your project as a Gradle dependency](#add-artifact-to-gradle-project)
38+
- **Option B:** Add gradle or maven dependency to your project: [TODO N/A for Beta](https://mvnrepository.com)
39+
2. Implement the `TracingRequestHandler` interface as shown in the [example](#example-usage), defining the Lambda function input and output types that your function requires.
40+
3. Override the `doHandleRequest` method from the interface and execute your function logic within it. *Note:* If you are refactoring a pre-existing Lambda handler to take advantage of this SDK's tracing request handler make sure that it overrides `doHandleRequest` but not `handleRequest`.
41+
4. Register the OpenTracing Tracer of your choice.
42+
5. See Amazon's documentation on [creating a ZIP deployment package for a Java Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/create-deployment-pkg-zip-java.html)
43+
6. When creating your Lambda function in AWS Lambda console the handler for the given example would be entered as `com.handler.example.MyLambdaHandler::handleRequest` or just `com.handler.example.MyLambdaHandler`, the latter of which will use `handleRequest` as the handler method by default. *Note:* `handleRequest` is used as the handler entry point as it will call `doHandleRequest`.
44+
45+
## Build the Project
46+
47+
Run jar task: `./gradlew java-aws-lambda:jar`
48+
49+
Artifact: `java-aws-lambda/java-aws-lambda/build/libs/java-aws-lambda.jar`
50+
51+
## Add Artifact to Gradle Project
52+
53+
Include the jar by adding it as a dependency in your `build.gradle` file:
54+
55+
```groovy
56+
dependencies {
57+
compile files('/path/to/java-aws-lambda.jar')
58+
}
59+
```
60+
61+
## Example Usage
62+
63+
```java
64+
package com.handler.example;
65+
66+
import com.amazonaws.services.lambda.runtime.Context;
67+
import io.opentracing.contrib.aws.TracingRequestHandler;
68+
import io.opentracing.util.GlobalTracer;
69+
70+
import java.util.Map;
71+
72+
/**
73+
* Tracing request handler that creates a span on every invocation of a Lambda.
74+
*
75+
* @param Map<String, Object> The Lambda Function input
76+
* @param String The Lambda Function output
77+
*/
78+
public class MyLambdaHandler implements TracingRequestHandler<Map<String, Object>, String> {
79+
static {
80+
// TODO Obtain an instance of the OpenTracing Tracer of your choice
81+
Tracer tracer = new CustomTracer(...);
82+
// Register your tracer as the Global Tracer
83+
GlobalTracer.register(tracer);
84+
}
85+
86+
/**
87+
* Method that handles the Lambda function request.
88+
*
89+
* @param input The Lambda Function input
90+
* @param context The Lambda execution environment context object
91+
* @return String The Lambda Function output
92+
*/
93+
@Override
94+
public String doHandleRequest(Map<String, Object> input, Context context) {
95+
// TODO Your function logic here
96+
return "Lambda Function output";
97+
}
98+
}
99+
```

build.gradle

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
plugins {
2+
id 'java'
3+
}
4+
5+
sourceCompatibility = JavaVersion.VERSION_1_8
6+
targetCompatibility = JavaVersion.VERSION_1_8
7+
8+
allprojects {
9+
repositories {
10+
mavenCentral()
11+
}
12+
}

gradle/wrapper/gradle-wrapper.jar

54.9 KB
Binary file not shown.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#Wed Jan 16 18:18:29 PST 2019
2+
distributionBase=GRADLE_USER_HOME
3+
distributionPath=wrapper/dists
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists
6+
distributionUrl=https\://services.gradle.org/distributions/gradle-4.10.2-all.zip

gradlew

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
#!/usr/bin/env sh
2+
3+
##############################################################################
4+
##
5+
## Gradle start up script for UN*X
6+
##
7+
##############################################################################
8+
9+
# Attempt to set APP_HOME
10+
# Resolve links: $0 may be a link
11+
PRG="$0"
12+
# Need this for relative symlinks.
13+
while [ -h "$PRG" ] ; do
14+
ls=`ls -ld "$PRG"`
15+
link=`expr "$ls" : '.*-> \(.*\)$'`
16+
if expr "$link" : '/.*' > /dev/null; then
17+
PRG="$link"
18+
else
19+
PRG=`dirname "$PRG"`"/$link"
20+
fi
21+
done
22+
SAVED="`pwd`"
23+
cd "`dirname \"$PRG\"`/" >/dev/null
24+
APP_HOME="`pwd -P`"
25+
cd "$SAVED" >/dev/null
26+
27+
APP_NAME="Gradle"
28+
APP_BASE_NAME=`basename "$0"`
29+
30+
# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
31+
DEFAULT_JVM_OPTS=""
32+
33+
# Use the maximum available, or set MAX_FD != -1 to use that value.
34+
MAX_FD="maximum"
35+
36+
warn () {
37+
echo "$*"
38+
}
39+
40+
die () {
41+
echo
42+
echo "$*"
43+
echo
44+
exit 1
45+
}
46+
47+
# OS specific support (must be 'true' or 'false').
48+
cygwin=false
49+
msys=false
50+
darwin=false
51+
nonstop=false
52+
case "`uname`" in
53+
CYGWIN* )
54+
cygwin=true
55+
;;
56+
Darwin* )
57+
darwin=true
58+
;;
59+
MINGW* )
60+
msys=true
61+
;;
62+
NONSTOP* )
63+
nonstop=true
64+
;;
65+
esac
66+
67+
CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
68+
69+
# Determine the Java command to use to start the JVM.
70+
if [ -n "$JAVA_HOME" ] ; then
71+
if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
72+
# IBM's JDK on AIX uses strange locations for the executables
73+
JAVACMD="$JAVA_HOME/jre/sh/java"
74+
else
75+
JAVACMD="$JAVA_HOME/bin/java"
76+
fi
77+
if [ ! -x "$JAVACMD" ] ; then
78+
die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
79+
80+
Please set the JAVA_HOME variable in your environment to match the
81+
location of your Java installation."
82+
fi
83+
else
84+
JAVACMD="java"
85+
which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
86+
87+
Please set the JAVA_HOME variable in your environment to match the
88+
location of your Java installation."
89+
fi
90+
91+
# Increase the maximum file descriptors if we can.
92+
if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
93+
MAX_FD_LIMIT=`ulimit -H -n`
94+
if [ $? -eq 0 ] ; then
95+
if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
96+
MAX_FD="$MAX_FD_LIMIT"
97+
fi
98+
ulimit -n $MAX_FD
99+
if [ $? -ne 0 ] ; then
100+
warn "Could not set maximum file descriptor limit: $MAX_FD"
101+
fi
102+
else
103+
warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
104+
fi
105+
fi
106+
107+
# For Darwin, add options to specify how the application appears in the dock
108+
if $darwin; then
109+
GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
110+
fi
111+
112+
# For Cygwin, switch paths to Windows format before running java
113+
if $cygwin ; then
114+
APP_HOME=`cygpath --path --mixed "$APP_HOME"`
115+
CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
116+
JAVACMD=`cygpath --unix "$JAVACMD"`
117+
118+
# We build the pattern for arguments to be converted via cygpath
119+
ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
120+
SEP=""
121+
for dir in $ROOTDIRSRAW ; do
122+
ROOTDIRS="$ROOTDIRS$SEP$dir"
123+
SEP="|"
124+
done
125+
OURCYGPATTERN="(^($ROOTDIRS))"
126+
# Add a user-defined pattern to the cygpath arguments
127+
if [ "$GRADLE_CYGPATTERN" != "" ] ; then
128+
OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
129+
fi
130+
# Now convert the arguments - kludge to limit ourselves to /bin/sh
131+
i=0
132+
for arg in "$@" ; do
133+
CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
134+
CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option
135+
136+
if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition
137+
eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
138+
else
139+
eval `echo args$i`="\"$arg\""
140+
fi
141+
i=$((i+1))
142+
done
143+
case $i in
144+
(0) set -- ;;
145+
(1) set -- "$args0" ;;
146+
(2) set -- "$args0" "$args1" ;;
147+
(3) set -- "$args0" "$args1" "$args2" ;;
148+
(4) set -- "$args0" "$args1" "$args2" "$args3" ;;
149+
(5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
150+
(6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
151+
(7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
152+
(8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
153+
(9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
154+
esac
155+
fi
156+
157+
# Escape application args
158+
save () {
159+
for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
160+
echo " "
161+
}
162+
APP_ARGS=$(save "$@")
163+
164+
# Collect all arguments for the java command, following the shell quoting and substitution rules
165+
eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
166+
167+
# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
168+
if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then
169+
cd "$(dirname "$0")"
170+
fi
171+
172+
exec "$JAVACMD" "$@"

java-aws-lambda/build.gradle

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
apply plugin: 'java'
2+
3+
dependencies {
4+
// TODO make this provided instead of compile?
5+
compile 'com.amazonaws:aws-lambda-java-core:1.1.0'
6+
compile 'com.amazonaws:aws-lambda-java-events:2.2.2' // 2.2.2 is earliest version that has all needed event sources
7+
compile 'com.amazonaws:aws-java-sdk-s3:1.11.163'
8+
compile 'com.amazonaws:aws-java-sdk-kinesis:1.11.163'
9+
compile 'com.amazonaws:aws-java-sdk-dynamodb:1.11.163'
10+
compile 'com.googlecode.json-simple:json-simple:1.1'
11+
compile('io.opentracing:opentracing-api:0.31.0') { transitive = false }
12+
compile('io.opentracing:opentracing-util:0.31.0') { transitive = false }
13+
compile('io.opentracing:opentracing-noop:0.31.0') { transitive = false }
14+
15+
testCompile 'junit:junit:4.12'
16+
testCompile 'io.opentracing:opentracing-mock:0.31.0'
17+
}
18+
19+
jar {
20+
manifest {
21+
attributes 'Implementation-Title': 'Java AWS Lambda OpenTracing Instrumentation', 'Implementation-Version': '1.0.1'
22+
}
23+
24+
// TODO, we don't really want all deps, at least I don't think
25+
from {
26+
configurations.compile.collect { it.isDirectory() ? it : zipTree(it) }
27+
}
28+
}
29+
30+
31+
32+

0 commit comments

Comments
 (0)