{"id":23330500,"url":"https://github.com/iopipe/iopipe-java","last_synced_at":"2025-09-14T15:07:09.908Z","repository":{"id":57729561,"uuid":"113876289","full_name":"iopipe/iopipe-java","owner":"iopipe","description":"AWS Lambda telemetry for Java","archived":false,"fork":false,"pushed_at":"2022-07-15T21:06:11.000Z","size":1995,"stargazers_count":17,"open_issues_count":8,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-19T20:03:37.318Z","etag":null,"topics":["aws","aws-lambda","devops","iopipe","iopipe-agent","java","lambda","monitoring","serverless"],"latest_commit_sha":null,"homepage":"https://www.iopipe.com/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iopipe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-11T15:33:50.000Z","updated_at":"2021-02-17T11:25:29.000Z","dependencies_parsed_at":"2022-09-11T06:20:39.506Z","dependency_job_id":null,"html_url":"https://github.com/iopipe/iopipe-java","commit_stats":null,"previous_names":["iopipe/iopipe-java-core"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/iopipe/iopipe-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iopipe","download_url":"https://codeload.github.com/iopipe/iopipe-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iopipe%2Fiopipe-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275121428,"owners_count":25409034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","devops","iopipe","iopipe-agent","java","lambda","monitoring","serverless"],"created_at":"2024-12-20T22:18:15.615Z","updated_at":"2025-09-14T15:07:09.871Z","avatar_url":"https://github.com/iopipe.png","language":"Java","readme":"**✨Special Announcement: We've Joined New Relic Serverless!**\n**Get ready to function faster with full visibility into your serverless applications—and everything else. [Read our founders' note to learn more.](https://read.iopipe.com/founders-note-iopipe-new-relic-acquisition-c15eeda47151)**\n\nIOpipe Telemetry Agent for Java\n--------------------------------------------\n[![Download](https://api.bintray.com/packages/iopipe/iopipe/iopipe/images/download.svg) ](https://bintray.com/iopipe/iopipe/iopipe/_latestVersion)[![Build status](https://circleci.com/gh/iopipe/iopipe-java.svg?style=shield\u0026circle-token=b9a08049964f555f38ab316ba535369aa5fe8252\n)](https://circleci.com/gh/iopipe/iopipe-java)[![Javadocs](https://www.javadoc.io/badge/com.iopipe/iopipe.svg)](https://www.javadoc.io/doc/com.iopipe/iopipe)\n\nThis project provides analytics and distributed tracing for event-driven\napplications running on AWS Lambda using [IOpipe](https://www.iopipe.com).\n\nIt is licensed under the Apache 2.0.\n\n * [Building With IOpipe](#building-with-iopipe)\n   * [Maven](#maven)\n   * [Gradle](#gradle)\n * [Configuration](#configuration)\n * [Wrapping Your Lambda](#wrapping-your-lambda)\n   * [Generic Entry Point Wrappers](#generic-entry-point-wrappers)\n     * [`RequestHandler`](#requesthandler)\n     * [`RequestStreamHandler`](#requeststreamhandler)\n   * [Implement `com.iopipe.SimpleRequestHandlerWrapper`](#implement-comiopipesimplerequesthandlerwrapper)\n   * [Implement `com.iopipe.SimpleRequestStreamHandlerWrapper`](#implement-comiopipesimplerequeststreamhandlerwrapper)\n   * [Wrapping Without A Helper Class](#wrapping-without-a-helper-class)\n * [Accessing IOpipe's `IOpipeExecution` Instance](#accessing-iopipes-iopipeexecution-instance)\n * [Accessing the AWS `Context` Object](#accessing-the-aws-context-object)\n * [Measuring and Monitoring](#measuring-and-monitoring)\n   * [Custom Metrics](#custom-metrics)\n   * [Event Info](#event-info)\n   * [Labels](#labels)\n   * [Profiling](#profiling)\n   * [Tracing](#tracing)\n   * [Logging](#logging)\n * [Resources](#resources)\n\n# Building With IOpipe\n\nThis agent is available in Maven Central and Bintray and either can be used for\nincluding the agent in your library.\n\n## Maven\n\nYour `pom.xml` file may be modified to include the following dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.iopipe\u003c/groupId\u003e\n  \u003cartifactId\u003eiopipe\u003c/artifactId\u003e\n  \u003cversion\u003e${iopipe.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nFind the latest version here (the format of the version will be `n.n.n`):\n\n * \u003chttps://github.com/iopipe/iopipe-java/releases\u003e\n * \u003chttps://search.maven.org/artifact/com.iopipe/iopipe\u003e\n * \u003chttps://bintray.com/iopipe/iopipe/iopipe/_latestVersion\u003e\n\nIt is highly recommended that you use the [Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/index.html)\nfor Maven since AWS requires that all classes and files are packed into a\nsingle JAR.\n\nIf you are using third-party IOpipe plugins or are writing your own you should\nin your POM include the [service resource transformer for shading](https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#ServicesResourceTransformer).\n\nIf your JAR file is too big you may try [reducing the size of your JAR using the shade plugin](https://maven.apache.org/plugins/maven-shade-plugin/examples/includes-excludes.html).\nIf that does not reduce the size of your JAR enough and you need more space\nyou can __strip all debugging and source line information__, __which makes\ndebugging much more difficult__, by running `pack200 -r -G path-to-target.jar`.\n\n## Gradle\n\nFor a basic configuration with Gradle there is [an example build.gradle](https://github.com/iopipe/examples/blob/master/java/build.gradle) that you may use as a base for your\nproject.\n\n# Wrapping your Lambda\n\nThere are four ways to wrap your lambda:\n\n * Using one of the generic entry point wrappers.\n * If you are currently implementing `RequestHandler`,\n   extend the class `com.iopipe.SimpleRequestHandlerWrapper`.\n * If you are currently implementing `RequestStreamHandler`,\n   extend the class `com.iopipe.SimpleRequestStreamHandlerWrapper`.\n * You may also initialize the IOpipe wrapper yourself.\n\n## Generic Entry Point Wrappers\n\nBy setting the entry point of the lambda in the configuration to a specific\ngeneric handler class then setting `IOPIPE_GENERIC_HANDLER` you may wrap\nany standard AWS entry point with IOpipe without needing to modify any code.\n\nIf the exception `com.iopipe.generic.InvalidEntryPointException` or\n`com.iopipe.IOpipeFatalError` is thrown the message detail should specify\nmis-configuration or a handler that cannot be used.\n\n## `RequestHandler`\n\nSet the entry point of your lambda to:\n\n * `com.iopipe.generic.GenericAWSRequestHandler`.\n\nThe expected method signatures are:\n\n * `(T)`\n * `(T, Context)`\n * `(IOpipeExecution, T)`\n\n## `RequestStreamHandler`\n\nSet the entry point of your lambda to:\n\n * `com.iopipe.generic.GenericAWSRequestStreamHandler`\n\nThe expected method signatures are:\n\n * `(InputStream, OutputStream)`\n * `(InputStream, OutputStream, Context)`\n * `(IOpipeExecution, InputStream, OutputStream)`\n\n## Implement `com.iopipe.SimpleRequestHandlerWrapper`\n\nThis class provides an implementation of `RequestHandler\u003cI, O\u003e`.\n\nAdd the following import statement:\n\n```java\nimport com.iopipe.IOpipeExecution;\nimport com.iopipe.SimpleRequestHandlerWrapper;\n```\n\nAdd a class which extends:\n\n```java\nSimpleRequestHandlerWrapper\u003cI, O\u003e\n```\n\nImplement the following method:\n\n```java\nprotected O wrappedHandleRequest(IOpipeExecution __exec, I __input)\n```\n\n## Implement `com.iopipe.SimpleRequestStreamHandlerWrapper`\n\nThis class provides an implementation of `RequestStreamHandler`.\n\nAdd the following import statements:\n\n```java\nimport com.amazonaws.services.lambda.runtime.Context;\nimport com.iopipe.IOpipeExecution;\nimport com.iopipe.SimpleRequestStreamHandlerWrapper;\nimport java.io.InputStream;\nimport java.io.IOException;\nimport java.io.OutputStream;\n```\n\nAdd a class which extends:\n\n```java\nSimpleRequestStreamHandlerWrapper\n```\n\nImplement the following method:\n\n```java\nprotected void wrappedHandleRequest(IOpipeExecution __exec, InputStream __in, OutputStream __out) throws IOException\n```\n\n## Wrapping Without A Helper Class\n\nIf you are unable to wrap using the `SimpleRequestHandlerWrapper` or\n`SimpleRequestStreamHandlerWrapper` you may manually wrap your method and then\nexecute that method or code.\n\nAdd the following import statements:\n\n```java\nimport com.amazonaws.services.lambda.runtime.Context;\nimport com.iopipe.IOpipeService;\n```\n\nObtain an instance of `IOpipeService`:\n\n```java\nIOpipeService service = IOpipeService.instance();\n```\n\nRun by passing a lambda or a class which implements the functional interface\n`Function\u003cIOpipeExecution, R\u003e`, an input object may be specified which is\nusable by plugins that require it:\n\n```java\nservice.\u003cString\u003erun(context, (exec) -\u003e \"Hello World!\");\nservice.\u003cString\u003erun(context, (exec) -\u003e \"Hello World!\", input);\n```\n\n# Configuration\n\nIOpipe may be configured using system properties and/or environment variables.\nNote that on AWS Lambda, environment variables must be used.\nIf you do specify system properties then they will take precedence before\nenvironment variables.\n\n* `com.iopipe.enabled` or `IOPIPE_ENABLED`\n  * If this is set and if the value is `true` (ignoring case) then the library\n    will be enabled.\n  * If this is set to `false`.\n  * If this is not set then internally it is treated as being `true`.\n* `com.iopipe.installmethod` or `IOPIPE_INSTALL_METHOD`\n* `com.iopipe.timeoutwindow` or `IOPIPE_TIMEOUT_WINDOW`\n  * This time is subtracted from the duration that a lambda may operate on\n    the service.\n  * If this is zero then the window is disabled.\n  * If this is not set then it defaults to `150`.\n* `com.iopipe.token` or `IOPIPE_TOKEN`\n  * This represents the token of the IOpipe collector which is to obtain\n    statistics.\n  * This is the default token which will be used if no token was specified in\n    the client.\n  * If you need help looking for your token you can visit:\n    [Find your project token](https://dashboard.iopipe.com/install).\n * `com.iopipe.plugin.\u003cname\u003e` or `IOPIPE_\u003cNAME\u003e_ENABLED`\n   * If set to `true` then the specified plugin will be enabled.\n   * If set to `false` then the plugin will be disabled.\n   * If this is not set for a plugin then it will use the setting from the\n     plugin if it should be enabled by default or not.\n * `com.iopipe.handler`/`com.iopipe.generichandler` or\n   `IOPIPE_HANDLER`/`IOPIPE_GENERIC_HANDLER`\n   * This specifies the class (and optionally the method) to be used by the\n     generic handler to wrap with IOpipe.\n   * `com.example`, implies that the `requestHandler` method be used.\n   * `com.example::requestHandler` specifies both a class and method.\n * `com.iopipe.collectorurl` or `IOPIPE_COLLECTOR_URL`\n   * Alternative URL for the collector, this is mostly used for debugging and\n     experimentation with newer collectors.\n\nAlternatively a configuration may be specified in the root of the JAR with a\nstandard properties format (`key=value`) which is named `iopipe.properties`.\nThe configuration values are only used if they have not been specified by\nsystem properties or environment variables. Generally using this is not\nrecommended because it would require a redeploy to change the settings. Also\nthe token itself is sensitive and should not be placed in the configuration.\n\nIOpipe uses tinylog for its internal logging, to make debug output from IOpipe\neasier to see tinylog can be configured using the following information located\nat:\n\n * \u003chttps://tinylog.org/configuration\u003e\n\nThe associated package is `com.iopipe`.\n\n# Accessing IOpipe's `IOpipeExecution` Instance\n\nIf `IOpipeExecution` needs to be obtained then you may use:\n\n * `IOpipeExecution.currentExecution()`\n\n# Accessing the AWS `Context` Object\n\nThe AWS `Context` object may be obtained by invoking `context()` on\nthe `IOpipeExecution` instance. For example:\n\n```java\nprotected final String wrappedHandleRequest(IOpipeExecution __exec, String __n)\n{\n    // Code here...\n    \n    Context context = __exec.context();\n    \n    // Code here...\n}\n```\n\n# Measuring and Monitoring\n\n## Custom Metrics\n\nTo use custom metrics, you can simply call the following two methods in the\n`IOpipeExecution` instance:\n\n```java\ncustomMetric(String name, String value)\ncustomMetric(String name, long value)\n```\n\nCalling either of these will add a custom metric with the specified name and\nthe given value. Custom metric names are limited to 128 characters.\n\n## Event Info\n\nThis plugin records input event types and includes in the report the origin\nof certain events.\n\nIt operates on the given input classes:\n\n * `com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent`\n * `com.amazonaws.services.lambda.runtime.events.CloudFrontEvent`\n * `com.amazonaws.services.lambda.runtime.events.KinesisEvent`\n * `com.amazonaws.services.lambda.runtime.events.KinesisFirehoseEvent`\n * `com.amazonaws.services.lambda.runtime.events.S3Event`\n * `com.amazonaws.services.lambda.runtime.events.ScheduledEvent`\n * `com.amazonaws.services.lambda.runtime.events.SNSEvent`\n * `com.amazonaws.services.lambda.runtime.events.SQSEvent`\n * `com.amazonaws.services.s3.event.S3EventNotification`\n\nBy default this plugin is enabled and requires no changes to your code unless\nyou are using IOpipe via the manual method. To disable the plugin you may set\nthe environment variable `IOPIPE_EVENT_INFO_ENABLED` to `false`.\n\nIf you are manually using IOpipe via the `IOpipeService` instance then you will\nneed to pass the input object for the plugin to see that object:\n\n```java\nservice.\u003cString\u003erun(context, (exec) -\u003e \"Hello World!\", input);\n```\n\n## Labels\n\nLabels allow you to add tags to invocations at run-time as needed. They can be\nadded by calling the following method in the `IOpipeExecution` instance:\n\n```java\nlabel(String name)\n```\n\nLabel names are limited to 128 characters.\n\n## Profiling\n\nInformation and usage on the profiler is contained within the following\ndocument:\n\n * [PROFILER.md](PROFILER.md)\n\n## Tracing\n\nThe tracing plugin is enabled by default and allows one to measure the\nperformance of operations within a single execution of a method. Since the\ntrace plugin will often be used, there are utility methods to make using it\nvery simple.\n\nImport the following classes:\n\n```java\nimport com.iopipe.plugin.trace.TraceMeasurement;\nimport com.iopipe.plugin.trace.TraceUtils;\n```\n\nMarks and measurements can be made by calling:\n\n```java\nTraceUtils.measure(String __name)\nTraceUtils.measure(IOpipeExecution execution, String __name)\n```\n\n`TraceMeasurement` can be used with try-with-resources like the following:\n\n```java\ntry (TraceMeasurement m = TraceUtils.measurement(\"watchthis\"))\n{\n    // Perform a lengthy operation\n}\n```\n\nor it may be used without try-with-resources and manually closed.\n\nIf the plugin is not enabled then the measurement will not record anything.\n\nDisabling the plugin can be done as followed:\n\n * Setting the system property `com.iopipe.plugin.trace` to `false`.\n * Setting the environment variable `IOPIPE_TRACE_ENABLED` to `false`.\n\n## Logging\n\nYou 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.\n\nIf you are using Log4j2 you may read the setup instructions ![here](https://github.com/iopipe/iopipe-java-logger-log4j2).\n\nIf you are using TinyLog you may read the setup instructions ![here](https://github.com/iopipe/https://github.com/iopipe/iopipe-java-logger-tinylog).\n\nOnce 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.\n\n# Resources\n\nFor this agent:\n\n * [Code of Conduct](CODE_OF_CONDUCT.md)\n * [JavaDocs](https://www.javadoc.io/doc/com.iopipe/iopipe)\n * [Writing and Using IOpipe Plugins for Java](PLUGINS.md)\n\nIn general:\n\n * [Java Programming Model on AWS](https://docs.aws.amazon.com/lambda/latest/dg/java-programming-model.html)\n * [Logging on AWS](https://docs.aws.amazon.com/lambda/latest/dg/java-logging.html)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiopipe%2Fiopipe-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiopipe%2Fiopipe-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiopipe%2Fiopipe-java/lists"}