This project provides analytics and distributed tracing for event-driven applications running on AWS Lambda using IOpipe.
It is licensed under the Apache 2.0.
- Building With IOpipe
- Configuration
- Wrapping Your Lambda
- Accessing IOpipe's
IOpipeExecution
Instance - Accessing the AWS
Context
Object - Measuring and Monitoring
- Resources
This agent is available in Maven Central and Bintray and either can be used for including the agent in your library.
Your pom.xml
file may be modified to include the following dependency:
<dependency>
<groupId>com.iopipe</groupId>
<artifactId>iopipe</artifactId>
<version>${iopipe.version}</version>
</dependency>
Find the latest version here (the format of the version will be n.n.n
):
- https://github.com/iopipe/iopipe-java/releases
- https://search.maven.org/artifact/com.iopipe/iopipe
- https://bintray.com/iopipe/iopipe/iopipe/_latestVersion
It is highly recommended that you use the Shade Plugin for Maven since AWS requires that all classes and files are packed into a single JAR.
If you are using third-party IOpipe plugins or are writing your own you should in your POM include the service resource transformer for shading.
If your JAR file is too big you may try reducing the size of your JAR using the shade plugin.
If that does not reduce the size of your JAR enough and you need more space
you can strip all debugging and source line information, which makes
debugging much more difficult, by running pack200 -r -G path-to-target.jar
.
For a basic configuration with Gradle there is an example build.gradle that you may use as a base for your project.
There are four ways to wrap your lambda:
- Using one of the generic entry point wrappers.
- If you are currently implementing
RequestHandler
, extend the classcom.iopipe.SimpleRequestHandlerWrapper
. - If you are currently implementing
RequestStreamHandler
, extend the classcom.iopipe.SimpleRequestStreamHandlerWrapper
. - You may also initialize the IOpipe wrapper yourself.
By setting the entry point of the lambda in the configuration to a specific
generic handler class then setting IOPIPE_GENERIC_HANDLER
you may wrap
any standard AWS entry point with IOpipe without needing to modify any code.
If the exception com.iopipe.generic.InvalidEntryPointException
or
com.iopipe.IOpipeFatalError
is thrown the message detail should specify
mis-configuration or a handler that cannot be used.
Set the entry point of your lambda to:
com.iopipe.generic.GenericAWSRequestHandler
.
The expected method signatures are:
(T)
(T, Context)
(IOpipeExecution, T)
Set the entry point of your lambda to:
com.iopipe.generic.GenericAWSRequestStreamHandler
The expected method signatures are:
(InputStream, OutputStream)
(InputStream, OutputStream, Context)
(IOpipeExecution, InputStream, OutputStream)
This class provides an implementation of RequestHandler<I, O>
.
Add the following import statement:
import com.iopipe.IOpipeExecution;
import com.iopipe.SimpleRequestHandlerWrapper;
Add a class which extends:
SimpleRequestHandlerWrapper<I, O>
Implement the following method:
protected O wrappedHandleRequest(IOpipeExecution __exec, I __input)
This class provides an implementation of RequestStreamHandler
.
Add the following import statements:
import com.amazonaws.services.lambda.runtime.Context;
import com.iopipe.IOpipeExecution;
import com.iopipe.SimpleRequestStreamHandlerWrapper;
import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;
Add a class which extends:
SimpleRequestStreamHandlerWrapper
Implement the following method:
protected void wrappedHandleRequest(IOpipeExecution __exec, InputStream __in, OutputStream __out) throws IOException
If you are unable to wrap using the SimpleRequestHandlerWrapper
or
SimpleRequestStreamHandlerWrapper
you may manually wrap your method and then
execute that method or code.
Add the following import statements:
import com.amazonaws.services.lambda.runtime.Context;
import com.iopipe.IOpipeService;
Obtain an instance of IOpipeService
:
IOpipeService service = IOpipeService.instance();
Run by passing a lambda or a class which implements the functional interface
Function<IOpipeExecution, R>
, an input object may be specified which is
usable by plugins that require it:
service.<String>run(context, (exec) -> "Hello World!");
service.<String>run(context, (exec) -> "Hello World!", input);
IOpipe may be configured using system properties and/or environment variables. Note that on AWS Lambda, environment variables must be used. If you do specify system properties then they will take precedence before environment variables.
com.iopipe.enabled
orIOPIPE_ENABLED
- If this is set and if the value is
true
(ignoring case) then the library will be enabled. - If this is set to
false
. - If this is not set then internally it is treated as being
true
.
- If this is set and if the value is
com.iopipe.installmethod
orIOPIPE_INSTALL_METHOD
com.iopipe.timeoutwindow
orIOPIPE_TIMEOUT_WINDOW
- This time is subtracted from the duration that a lambda may operate on the service.
- If this is zero then the window is disabled.
- If this is not set then it defaults to
150
.
com.iopipe.token
orIOPIPE_TOKEN
- This represents the token of the IOpipe collector which is to obtain statistics.
- This is the default token which will be used if no token was specified in the client.
- If you need help looking for your token you can visit: Find your project token.
com.iopipe.plugin.<name>
orIOPIPE_<NAME>_ENABLED
- If set to
true
then the specified plugin will be enabled. - If set to
false
then the plugin will be disabled. - If this is not set for a plugin then it will use the setting from the plugin if it should be enabled by default or not.
- If set to
com.iopipe.handler
/com.iopipe.generichandler
orIOPIPE_HANDLER
/IOPIPE_GENERIC_HANDLER
- This specifies the class (and optionally the method) to be used by the generic handler to wrap with IOpipe.
com.example
, implies that therequestHandler
method be used.com.example::requestHandler
specifies both a class and method.
com.iopipe.collectorurl
orIOPIPE_COLLECTOR_URL
- Alternative URL for the collector, this is mostly used for debugging and experimentation with newer collectors.
Alternatively a configuration may be specified in the root of the JAR with a
standard properties format (key=value
) which is named iopipe.properties
.
The configuration values are only used if they have not been specified by
system properties or environment variables. Generally using this is not
recommended because it would require a redeploy to change the settings. Also
the token itself is sensitive and should not be placed in the configuration.
IOpipe uses tinylog for its internal logging, to make debug output from IOpipe easier to see tinylog can be configured using the following information located at:
The associated package is com.iopipe
.
If IOpipeExecution
needs to be obtained then you may use:
IOpipeExecution.currentExecution()
The AWS Context
object may be obtained by invoking context()
on
the IOpipeExecution
instance. For example:
protected final String wrappedHandleRequest(IOpipeExecution __exec, String __n)
{
// Code here...
Context context = __exec.context();
// Code here...
}
To use custom metrics, you can simply call the following two methods in the
IOpipeExecution
instance:
customMetric(String name, String value)
customMetric(String name, long value)
Calling either of these will add a custom metric with the specified name and the given value. Custom metric names are limited to 128 characters.
This plugin records input event types and includes in the report the origin of certain events.
It operates on the given input classes:
com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent
com.amazonaws.services.lambda.runtime.events.CloudFrontEvent
com.amazonaws.services.lambda.runtime.events.KinesisEvent
com.amazonaws.services.lambda.runtime.events.KinesisFirehoseEvent
com.amazonaws.services.lambda.runtime.events.S3Event
com.amazonaws.services.lambda.runtime.events.ScheduledEvent
com.amazonaws.services.lambda.runtime.events.SNSEvent
com.amazonaws.services.lambda.runtime.events.SQSEvent
com.amazonaws.services.s3.event.S3EventNotification
By default this plugin is enabled and requires no changes to your code unless
you are using IOpipe via the manual method. To disable the plugin you may set
the environment variable IOPIPE_EVENT_INFO_ENABLED
to false
.
If you are manually using IOpipe via the IOpipeService
instance then you will
need to pass the input object for the plugin to see that object:
service.<String>run(context, (exec) -> "Hello World!", input);
Labels allow you to add tags to invocations at run-time as needed. They can be
added by calling the following method in the IOpipeExecution
instance:
label(String name)
Label names are limited to 128 characters.
Information and usage on the profiler is contained within the following document:
The tracing plugin is enabled by default and allows one to measure the performance of operations within a single execution of a method. Since the trace plugin will often be used, there are utility methods to make using it very simple.
Import the following classes:
import com.iopipe.plugin.trace.TraceMeasurement;
import com.iopipe.plugin.trace.TraceUtils;
Marks and measurements can be made by calling:
TraceUtils.measure(String __name)
TraceUtils.measure(IOpipeExecution execution, String __name)
TraceMeasurement
can be used with try-with-resources like the following:
try (TraceMeasurement m = TraceUtils.measurement("watchthis"))
{
// Perform a lengthy operation
}
or it may be used without try-with-resources and manually closed.
If the plugin is not enabled then the measurement will not record anything.
Disabling the plugin can be done as followed:
- Setting the system property
com.iopipe.plugin.trace
tofalse
. - Setting the environment variable
IOPIPE_TRACE_ENABLED
tofalse
.
For this agent:
In general: