npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

serverless-plugin-epsagon

v1.12.4

Published

Epsagon's plugin for the serverless framework

Downloads

1,474

Readme

serverless semantic-release npm version Build Status

Epsagon Serverless Framework Plugin

Epsagon's plugin for the Serverless Framework, that enables tracing for your functions.

Contents

Installation

Install Epsagon's Library

For Node.js functions:

npm install epsagon

For Python functions:

pip install epsagon

If you are using serverless-python-requirements plugin, also add epsagon to your requirements.txt file.

Install The Plugin

Using the Serverless Framework:

sls plugin install --name serverless-plugin-epsagon

Or using NPM:

npm install --save-dev serverless-plugin-epsagon

When installing with NPM, add the plugin to your serverless.yml file:

plugins:
  - serverless-plugin-epsagon

For the best results, make sure this is the first plugin specified in your plugins list.

Usage

When using this plugin, make sure to use just this method for tracing. You don't need to manually copy or import the epsagon library to your code, nor enable the auto-tracing.

To get started with the plugin, open your serverless.yml, and add the following snippet in the custom section:

custom:
  epsagon:
    token: epsagon-token
    appName: app-name-stage

You can find your token in the Epsagon settings page.

The plugin will be activated automatically during sls deploy, sls package and sls invoke local events automatically.

To cleanup any Epsagon-related files run sls epsagon clean and it will clean up files after deployment (can happen when you stop in the middle of a deployment)

Configuration

Service Level Options

These options are defined at the service level, under the custom.epsagon section of your serverless.yml file. Any function level option will override options defined here.

Available options:

|Parameter |Mandatory/Optional|Default Value |Description | |-----------------|------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------| |token |Mandatory |- |Epsagon account token. You can find your token in the Epsagon settings page. | |appName |Optional | `` |Application name that will be set for traces | |disable |Optional | false | When set to true it disables Epsagon for the entire service. When this option is active wrapping your functions with Epsagon will be skipped.| |metadataOnly |Optional |false |Whether to send only the metadata (true) or also the payloads (false) | |handlersDirName|Optional |epsagon_handlers|Customize the name of the directory Epsagon stores its handlers in. Do not use this option unless you know what you are doing. | |packageJsonPath|Optional |./package.json |Customize the path of your package.json | |collectorURL |Optional |- |The address of the trace collector to send trace to | |ignoredKeys |Optional |- |May contain strings (will perform a loose match, so that First Name also matches first_name) | |urlsToIgnore |Optional |- |Ignore HTTP calls to specific domains | |payloadsToIgnore |Optional |- | Array of dictionaries to not instrument. Example: '{"source": "serverless-plugin-warmup"}' | |labels |Optional |[] |Global labels applied to all traces. For example "[['key', 'val']]". (Not available for Python) | |wrapper|Optional |lambda_wrapper/lambdaWrapper | The wrapper to use to wrap this function. See wrappers| |

Function Level Options

These options are defined at the function level, under the epsagon member of your function in the serverless.yml file. Configuring the values at the function level, will override the service level configurations.

For example:

functions:
  example-func:
    handler: handler.handle
    epsagon:
      wrapper: lambda_wrapper
      disable: true

Available options:

|Parameter|Mandatory/Optional|Default Value |Description | |---------|------------------|----------------------------------------------------------------------------------------------------|-------------------------------------------------------| |disable|Optional | false | When set to true it disables Epsagon for the function.| |appName|Optional | `` |Application name that will be set for traces | |wrapper|Optional |lambda_wrapper/lambdaWrapper | The wrapper to use to wrap this function. See wrappers| |

wrappers

  • Python functions:
    • lambda_wrapper - regular lambda wrapper
    • step_lambda_wrapper - Used to wrap step functions
    • python_wrapper - Used to wrap regular Python functions (doesn't have to run on Lambda)
    • tencent_function_wrapper - Wrapper for Tencent Cloud Serverless Cloud Functions
  • Node.js functions:
    • lambdaWrapper - regular lambda wrapper
    • stepLambdaWrapper - Used to wrap step functions
    • nodeWrapper - Used to wrap regular Node functions (doesn't have to run on Lambda)
    • tencentFunctionWrapper - Wrapper for Tencent Cloud Serverless Cloud Functions

Troubleshooting

Does this plugin work with webpack?

Yes. you can use webpack or any serverless plugins utilizing webpack with this plugin. Just make sure to specify this plugin before any other plugin in your serverless.yml:

plugins:
- serverless-plugin-epsagon
- serverless-webpack
- any-other-plugin

In order to get the full tracing ability of epsagon, please specify any packages that should be traced (e.g. aws-sdk, pg, mongodb) as external in your webpack config.

Is TypeScript supported?

Yes. Just make sure to specify this plugin first in your serverless.yml

Unable to import module epsagon_handlers error:

During deployment, the plugin creates epsagon_handlers/ dir to wrap the function. Please make sure this dir is not excluded in the configuration.

[Node.js] Cannot find module 'epsagon' error:

node_modules must be included in the function package being deployed, make sure that node_modules is not excluded somewhere. An example bellow of how your serverless.yml could look like:

...
package:
individually: true
exclude:
    - ./** # Excludes everything
include: # Include necessary dependencies for your function to work
    - "node_modules/**"
    - "epsagon_handlers/**"
...
functions:
    helloWorld:
        handler: helloWorld.handler
        package:
        include:
            - helloWorld.js # Include only your function
...

[Node.js] Epsagon's Node library must be installed in order to use this plugin! error:

The plugin verifies that epsagon module exists in your dependencies section of your ./package.json before deployment. In some cases, the package.json might be in a different path. You can easily update it using packageJsonPath parameter, for example:

custom:
  epsagon:
    packageJsonPath: `../../dir/package.json`

Can I use this plugin together with another methods of tracing using Epsagon?

No. Make sure to choose only a single way to trace your functions.

In my AWS Lambda I'm accessing a local file. Using the plugin causes an issue.

If you are using a relative path to a local file in your Lambda function, using the plugin might cause some issues. The reason for that is that the plugin changes the location of your Lambda handler.

Getting Help

If you have any issue around using the library or the product, please don't hesitate to:

  • Use the documentation.
  • Use the help widget inside the product.
  • Open an issue in GitHub.

Opening Issues

If you encounter a bug with the Epsagon library for Node.js, we want to hear about it.

When opening a new issue, please provide as much information about the environment:

  • Library version, runtime version, dependencies, etc.
  • Snippet of the usage.
  • A reproducible example can really help.

The GitHub issues are intended for bug reports and feature requests. For help and questions about Epsagon, use the help widget inside the product.

License

Provided under the MIT license. See LICENSE for details.

Copyright 2020, Epsagon