Elven Serverless Plugin

The Elven Serverless Plugin simplifies the automatic instrumentation of your AWS Lambda functions in the Serverless Framework, by adding the observability Layer, configuring the environment variables, and preparing your functions to send traces, logs, and metrics to your LGTM stack.

Prerequisites

• Node.js 14.x or higher

• Serverless Framework installed (npm install -g serverless)

• AWS account configured

• Access to the Elven Observability dashboard

Installation

Add the plugin to your project.

# with Yarn
yarn add elven-serverless-plugin

# with NPM
npm install elven-serverless-plugin

Configuration in the Serverless Framework

In your serverless.yml (ou .ts, .js) file, add the plugin to the list.

plugins:
  - elven-serverless-plugin

If you are already using other plugins, just add the elven-serverless-plugin alongside them.

Then, configure the plugin in the custom section.

custom:
  elvenPlugin:
    tenant: "${env:TENANT_ID}"            # The Tenant ID supplied in Elven Observability
    token: "${env:OTEL_API_TOKEN}"        # The token generated within Elven Observability
    endpoint: "${env:COLLECTOR_URL}"      # URL of your OTLP Collector
    loki_url: "${env:LOKI_URL}"           # Loki URL (optional, default is provided)
    env: ${opt:stage, 'dev'}              # Environment (dev, staging, prod)
    region: ${opt:region, 'us-east-1'}    # AWS Region
    version: 5                            # Instrumentation Layer Version

About the values

• You can pass the values directly (plain text), for example:

tenant: "acme-tenant"
token: "eyJhbGciOiJIUzI1NiIs..."
endpoint: "<https://my-collector.com/otlp/v1>"

• Best practice: use environment variables to avoid exposing sensitive data in the code.

Example of a .env file

TENANT_ID=acme-tenant
OTEL_API_TOKEN=eyJhbGciOiJIUzI1NiIs...
COLLECTOR_URL=https://collector.elvenobservability.com/otlp/v1
LOKI_URL=https://loki.elvenobservability.com

How to obtain tenant and token

Go to https://elvenobservability.com/, log in to your dashboard, and generate the Tenant ID and API Token in the project settings section. If you experience any issues, our support team is ready to help. Reach out through the dashboard or contact your dedicated representative.

What the plugin does automatically

• Adds the observability Layer to your Lambda functions.

• Configures the necessary environment variables for OpenTelemetry and Loki.

• Generates standardized service names in the format: service_stage_functionName

• Allows disabling instrumentation for specific functions:

functions:
  myFunction:
    handler: handler.myFunction
    disableOtel: true

Deploy

Run the deploy of your service.

# Deploy to development environment
serverless deploy --stage dev --region us-east-1

# Deploy to production
serverless deploy --stage prod --region us-east-1

Verifying Instrumentation

1. After the deploy, go to the AWS Console.

2. Check if the Layer was added to your functions.

3. Review the environment variables in the Lambda settings.

4. Run a function and check the traces in the Elven dashboard.

Best practices

• Always use environment variables for token, tenant e endpoint.

• Set the Layer version in the elvenPlugin to ensure consistency across environments.

• Name your services and functions clearly to make analysis easier in Grafana and Loki.

• Review the injected variables in the function during deploy to ensure everything is correct.

Troubleshooting

Problem	Probable cause	What should be verified
Traces or logs are not showing up in Grafana.	Incorrect endpoint or token	Review the values in the environment.
Uninstrumented function	disableOtel: true Applied?	Confirm in the function config.
Lambda with high latency	Collector or Loki unavailable	Test the endpoint and review the timeout.
Missing variable in the function	Override in the function config?	Check the serverless.yml

Complete example

service: my-awesome-service

plugins:
  - elven-serverless-plugin

custom:
  elvenPlugin:
    tenant: "${env:TENANT_ID}"
    token: "${env:OTEL_API_TOKEN}"
    endpoint: "${env:COLLECTOR_URL}"
    loki_url: "${env:LOKI_URL}"
    env: ${opt:stage, 'dev'}
    region: ${opt:region, 'us-east-1'}
    version: 5

provider:
  name: aws
  runtime: nodejs18.x
  stage: ${opt:stage, 'dev'}
  region: ${opt:region, 'us-east-1'}

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: hello
          method: get

  processData:
    handler: handler.processData
    events:
      - sqs:
          arn: ${cf:my-queue.QueueArn}
    disableOtel: true  # Example: disables instrumentation in this function

  analyticsJob:
    handler: handler.analytics
    events:
      - schedule: rate(1 hour)

Additional Resources

• Serverless Framework documentation

• OpenTelemetry for Lambda

• AWS Lambda Layers

• Elven Support

Need help? Contact our support team through the Elven Observability dashboard or send an email to [email protected].