search

iopipe / iopipe-java

AWS Lambda telemetry for Java
https://www.iopipe.com/
Apache License 2.0
17 stars 8 forks source link
aws aws-lambda devops iopipe iopipe-agent java lambda monitoring serverless

readme

✨Special Announcement: We've Joined New Relic Serverless! Get ready to function faster with full visibility into your serverless applications—and everything else. Read our founders' note to learn more.

IOpipe Telemetry Agent for Java

Download Build statusJavadocs

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

This agent is available in Maven Central and Bintray and either can be used for including the agent in your library.

Maven

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):

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.

Gradle

For a basic configuration with Gradle there is an example build.gradle that you may use as a base for your project.

Wrapping your Lambda

There are four ways to wrap your lambda:

Generic Entry Point Wrappers

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.

RequestHandler

Set the entry point of your lambda to:

The expected method signatures are:

RequestStreamHandler

Set the entry point of your lambda to:

The expected method signatures are:

Implement com.iopipe.SimpleRequestHandlerWrapper

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)

Implement com.iopipe.SimpleRequestStreamHandlerWrapper

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

Wrapping Without A Helper Class

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);

Configuration

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.

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.

Accessing IOpipe's IOpipeExecution Instance

If IOpipeExecution needs to be obtained then you may use:

Accessing the AWS Context Object

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...
}

Measuring and Monitoring

Custom Metrics

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.

Event Info

This plugin records input event types and includes in the report the origin of certain events.

It operates on the given input classes:

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

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.

Profiling

Information and usage on the profiler is contained within the following document:

Tracing

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:

Logging

You send synchronous logs to IOpipe, bypassing Cloudwatch. Note that this will incur additional overhead in your invocations. This can be useful for doing local development, or if you're unable to connect Cloudwatch logs to IOpipe for async no-overhead logging.

If you are using Log4j2 you may read the setup instructions here.

If you are using TinyLog you may read the setup instructions here.

Once you’re setup, you will need to configure IOpipe to enable the logging plugin. You can do this by setting the IOPIPE_LOGGER_ENABLED environment variable to true in the AWS Lambda configuration.

Resources

For this agent:

In general: