https://github.com/iopipe/iopipe-js
Build and run serverless apps with confidence on AWS Lambda with Tracing, Profiling, Metrics, Monitoring, and more.
https://github.com/iopipe/iopipe-js
aws aws-lambda aws-lambda-node debugging iopipe iopipe-agent profiling serverless serverless-functions tracing
Last synced: 6 months ago
JSON representation
Build and run serverless apps with confidence on AWS Lambda with Tracing, Profiling, Metrics, Monitoring, and more.
- Host: GitHub
- URL: https://github.com/iopipe/iopipe-js
- Owner: iopipe
- License: apache-2.0
- Created: 2017-11-01T23:13:40.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-09T01:31:35.000Z (over 2 years ago)
- Last Synced: 2024-12-05T23:47:26.517Z (6 months ago)
- Topics: aws, aws-lambda, aws-lambda-node, debugging, iopipe, iopipe-agent, profiling, serverless, serverless-functions, tracing
- Language: Shell
- Homepage: https://www.iopipe.com
- Size: 1.17 MB
- Stars: 33
- Watchers: 3
- Forks: 10
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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.](https://read.iopipe.com/founders-note-iopipe-new-relic-acquisition-c15eeda47151)**
IOpipe Agent & Bundled Plugins
-----------------------------
[](https://badge.fury.io/js/%40iopipe%2Fiopipe)
[](https://iopipe.now.sh/)
[](https://github.com/semantic-release/semantic-release)
This package provides the IOpipe agent and plugins pre-bundled.
# Installation & usage
Install via npm:
```bash
npm install --save @iopipe/iopipe
```
Or via yarn:
```bash
yarn add @iopipe/iopipe
```
Then require this module, passing it an object with your project token ([get a free account](https://www.iopipe.com)), and it will automatically monitor and collect metrics from your applications running on AWS Lambda.
If you are using the Serverless Framework to deploy your lambdas, check out our [serverless plugin](https://github.com/iopipe/serverless-iopipe-layers).
Example:
```js
const iopipe = require('@iopipe/iopipe')({ token: 'PROJECT_TOKEN' });
exports.handler = iopipe((event, context) => {
context.succeed('This is my serverless function!');
});
```
By default this package will enable `@iopipe/trace` and `@iopipe/event-info` plugins. It also includes the `@iopipe/profiler` plugin, which is disabled by default. For more information on how to use IOpipe and these plugins, see the documentation below:
- [IOpipe Documentation](https://github.com/iopipe/iopipe-js-core#readme)
- [IOpipe Tracing Plugin Documentation](https://github.com/iopipe/iopipe-plugin-trace#readme)
- [IOpipe Event Info Plugin Documentation](https://github.com/iopipe/iopipe-js-event-info#readme)
- [IOpipe Profiler Plugin Documentation](https://github.com/iopipe/iopipe-plugin-profiler#readme)
Example With Tracing, Custom Metrics, and Labels (ES6 Module Format):
```js
import iopipe, {mark, metric, label} from '@iopipe/iopipe';
exports.handler = iopipe()(async (event, context) => {
// add a trace measurement for the database call
mark.start('db-call');
// fetch some data from the database
const rows = await sql(`select * from dogs where status = 'goodboy'`);
mark.end('db-call');
// add a custom metric for IOpipe search and alerts
metric('rows-from-db', rows.length);
// add a label to this invocation for easy filter/sort on dashboard.iopipe.com
label('used-db-cache');
context.succeed('This is my serverless function!');
});
```
# Lambda Layers
IOpipe publishes [AWS Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) which are publicly available on AWS. Using a framework that supports lambda layers (such as SAM or Serverless), you can use the following ARNs for your runtime:
* nodejs10.x: `arn:aws:lambda:$REGION:146318645305:layer:IOpipeNodeJS10:$VERSION_NUMBER`
* nodejs8.10: `arn:aws:lambda:$REGION:146318645305:layer:IOpipeNodeJS810:$VERSION_NUMBER`
Where `$REGION` is your AWS region and `$VERSION_NUMBER` is an integer representing the IOpipe release. You can get the version number via the [Releases](https://github.com/iopipe/iopipe-js/releases) page.
Then in your SAM template (for example), you can add:
```yaml
Globals:
Function:
Layers:
- arn:aws:lambda:us-east-1:146318645305:layer:IOpipeNodeJS810:1
```
And the IOpipe library will be included in your function automatically.
You can also wrap your IOpipe functions without a code change using layers. For example, in your SAM template you can do the following:
```yaml
Resources:
YourFunctionHere:
Type: 'AWS::Serverless::Function'
Properties:
CodeUri: path/to/your/code
# Automatically wraps the handler with IOpipe
Handler: @iopipe/iopipe.handler
Runtime: nodejs8.10
Environment:
Variables:
# Specifies which handler IOpipe should run
IOPIPE_HANDLER: path/to/your.handler
```
Or with the Serverless framework:
```yaml
functions:
your-function-here:
environment:
IOPIPE_HANDLER: path/to/your.handler
handler: @iopipe/iopipe.handler
layers:
- arn:aws:lambda:us-east-1:146318645305:layer:IOpipeNodeJS810:1
runtime: nodejs8.10
```
# Troubleshooting
## Lambda layers: ```Lambda can't find the file @iopipe/iopipe.js```
If you're seeing this error, it's likely that the node runtime isn't resolving ```NPM_PATH``` for the ```@iopipe/iopipe``` module in ```/opt/nodejs/node_modules```.
These steps should fix the problem:
1. Create an ```iopipe_wrapper.js``` script in your project's root.
2. The script's contents should be ```module.exports = require('@iopipe/iopipe');```. (And that's all that needs to be in it.)
3. Update the handler for your layer declaration to ```iopipe_wrapper.handler```.
# License
Apache 2.0