AWS Node.js용 람다 원시 추적

Instana AutoTrace 설정

Node.js 에 대한 인스턴스 AutoTrace 를 설정하면 AWS Lambda 함수를 추적할 수 있습니다. 이 기능은 Instana Lambda layer 및 사용자 정의 함수 핸들러를 사용하는 것입니다. 이 접근 방식은 Lambda 기능 코드를 수정할 필요가 없으며 구성을 통해 순수하게 수행된다. 또한 자동화되거나 람다 배치 파이프라인에 포함되기에 적합합니다.

Node.js 람다 함수의 추적을 사용하려면 다음 단계를 수행하십시오.

1. 함수에 인스턴스 Lambda를 추가하십시오.

   1. Lambda 함수의 설정 페이지에서, " Layers " 상자를 클릭한 다음, " Add a layer"를 클릭합니다.
   2. 팝업창이 열리면, "레이어 버전 ARN 제공"을 선택하고, 해당 지역에 해당하는 Instana Lambda Layer의 ARN을 복사하여 붙여넣으십시오. Instana Lambda Layer 섹션 에서 Instana Lambda Layer에 해당하는 ARN을 찾을 수 있습니다.

2. 람다 핸들러를 구성하십시오. CommonJS를 사용하는 경우 핸들러를 instana-aws-lambda-auto-wrap.handler 로 설정하십시오. ES 모듈 (ES6) (계층 버전 223에서 사용 가능) 을 사용하는 경우 핸들러를 instana-aws-lambda-auto-wrap-esm.handler 로 설정하십시오.

   람다 핸들러의 설정을 변경하려면 구성 페이지에서 "기본 설정" 섹션을 찾으십시오.

   

   편집을 클릭하고 "핸들러" 라는 필드에 instana-aws-lambda-auto-wrap.handler 을 삽입하십시오.

   

   인스턴스화 Lambda 계층은 자동으로 기본 Node.js 런타임 핸들러 index.handler을 트리거합니다. 사용자 정의 핸들러를 사용하는 경우, 환경 변수 LAMBDA_HANDLER 에 핸들러를 지정하여 인스턴스 Lambda 계층에 알리십시오. 설정해야 하는 모든 환경 변수에 대해서는 다음 섹션을 참조하십시오.

   Ambda 구성 페이지에 "Lambda가 instana-aws-lambda-auto-wrap.js파일을 찾을 수 없습니다." 와 같은 경고가 표시될 수 있습니다. 이는 구성 페이지로 리턴할 때 나중에 표시될 수도 있습니다. 이 경고가 당신을 혼란스럽게 하게 하지 마세요. 핸들러는 Instana Lambda 계층에 포함되어 있지만 AWS Lambda 구성 페이지에서는 이를 고려하지 않습니다.

3. 환경 변수 구성 다음 환경 변수를 추가하십시오.

   • INSTANA_ENDPOINT_URL: 서버가 없는 모니터링 엔드포인트입니다. https://serverless-로 시작하는 리젼에 올바른 값을 사용하십시오.
   • INSTANA_AGENT_KEY: 에이전트 키.
   • LAMBDA_HANDLER: 사용자 정의 핸들러를 설정합니다. 기본 파일이 myHandler함수를 내보내는 myModule.js인 경우, 환경 변수를 myModule.myHandler로 설정하십시오. 기본값은 index.handler입니다.

   다음 예에서, 원래의 메인 람다 핸들러는 index.js 이므로, 환경 변수 LAMBDA_HANDLER를 설정할 필요가 없습니다.

   다음 예에서, 원래의 메인 람다 핸들러는 server.js 이므로, 환경 변수 LAMBDA_HANDLER를 server.handler 로 설정해야 합니다.

   또한 인스턴스 설치로 이동하여 이러한 환경 변수의 올바른 값을 얻을 수 있습니다. " ... "->" 에이전트 "->" 인스턴스 설치 "-> 플랫폼:"AWS"-> 기술:"AWS Lambda ".

4. 람다 함수 정의를 저장합니다.

위에서 설명한 모든 단계는 다음과 같이 AWS 웹 콘솔 또는 일반적인 AWS 관리 도구를 통해 수행할 수 있습니다.

• aws 명령행 인터페이스
• serverless 프레임워크 CLI
• AWS 클라우드 개발 킷

다음은 AWS Lambda의 인스턴스 통합을 자동화하려는 경우 시작점으로 사용할 수 있는 예제 aws CLI 명령입니다.

# Do not copy and paste this verbatim!
# It will overwrite any previously defined collection of layers and
# environment variables.
aws --region $YOUR_REGION lambda update-function-configuration \
  --function-name $YOUR_LAMBDA_FUNCTION_NAME \
  --layers $INSTANA_LAYER_ARN \
  --handler instana-aws-lambda-auto-wrap.handler \
  --environment ""Variables={INSTANA_ENDPOINT_URL=... , INSTANA_AGENT_KEY=... , ...}""

Instana 람다 레이어

그만큼 Node.js 레이어에는 다음이 포함됩니다. 인스타나 AWS 람다 확장. 모니터링 데이터 및 추적은 Instana Lambda 확장으로 로컬로 오프로드된 다음 이를 Instana 백엔드로 전달합니다. 이 기능은 다음과 같은 이점을 제공합니다. Lambda 함수는 데이터가 Instana 백엔드로 전송될 때까지 기다리지 않고 핸들러가 완료된 후 즉시 호출 클라이언트에 응답합니다.

이 기능은 제한된 메모리로 구성된 Lambda 함수에 256MB 이상. 환경 변수를 설정하여 Instana Lambda 확장을 비활성화할 수 있습니다.INSTANA_DISABLE_LAMBDA_EXTENSION Lambda 함수의 비어 있지 않은 문자열로.

컨테이너 기반 함수를 위한 Instana 람다 레이어

팀이 컨테이너 기반 Lambda 배치를 사용하는 경우, icr.io/instana/aws-lambda-nodejs 에서 기본 컨테이너를 사용하거나 Docker파일에 다음 스니펫을 포함하고 빌드 시간 인수 를 적절한 버전으로 설정할 수 있습니다.

# This is the container image that delivers Instana's monitoring capabilities.
# It will not become the base image for your Lambda container image, it just provides a few files.
FROM icr.io/instana/aws-lambda-nodejs:latest as instana-layer

# This is the actual base image for your Lambda container image. You can also use any other base image that is suitable
# for container image based Lambda functions.
FROM public.ecr.aws/lambda/nodejs:14

# Copy Instana's Node.js monitoring components into your Lambda container image.
COPY --from=instana-layer /opt/extensions/ /opt/extensions/
COPY --from=instana-layer /opt/nodejs/ /opt/nodejs/

# The remainder of your Dockerfile, as it was without adding the Instana layer. The following is just an example:
COPY index.js package.json package-lock.json /var/task/
WORKDIR /var/task
RUN npm install

# Override the CMD. This can also be done as a parameter override outside of the Dockerfile, for example in the AWS console.
# If you use ES modules, use CMD [ "instana-aws-lambda-auto-wrap-esm.handler" ] instead.
CMD [ "instana-aws-lambda-auto-wrap.handler" ]

Instead of icr.io/instana/aws-lambda-nodejs:latest, you can also use a specific version of the Instana npm module @instana/aws-lambda greater or equal to 1.137.2 (see 변경 로그), so for example:

FROM icr.io/instana/aws-lambda-nodejs:1.140.1 as instana-layer

또는 최신 부/패치 릴리스를 허용하면서 주 버전만을 고정할 수 있습니다.

FROM icr.io/instana/aws-lambda-nodejs:1 as instana-layer

icr.io/instana/aws-lambda-nodejs 의 향후 버전은 이전 Lambda Node.js 런타임에 대한 지원을 삭제합니다. 예를 들어, 버전 icr.io/instana/aws-lambda-nodejs:2.0.0부터 nodejs8.x 에 대한 지원이 삭제됩니다. 이전 Lambda 런타임을 사용할 때는 주요 버전을 고정하는 것이 좋다.

Instana 람다 계층 및 수동 줄바꿈

위에서 설명한 대로 함수에 인스턴스 Lambda 계층을 추가할 수 있지만 instana-aws-lambda-auto-wrap.handler은 사용하지 마십시오. 특히 이는 "Node.js 8.10" 런타임을 기반으로 하는 AWS Lambda에 대한 권장 접근 방식입니다. 이 설정에 필요한 단계는 다음과 같습니다.

1. 함수에 인스턴스화 Lambda 계층을 추가한다. 위의 테이블에서 인스턴스 Lambda 계층의 ARN을 찾을 수 있습니다.
2. 환경 변수 INSTANA_ENDPOINT_URL 및 INSTANA_AGENT_KEY 를 필수 값으로 추가하십시오.
3. 핸들러를 수동으로 랩핑섹션에 따라 함수의 코드를 수정하십시오.

Instana/aws-lambda 수동으로 설치하기

인스턴스 Lambda 계층을 사용하는 대신, npm 패키지 @instana/aws-lambda 를 수동으로 설치하도록 선택할 수도 있습니다.

1. 프로젝트 디렉토리에서 npm install -S @instana/aws-lambda (또는 yarn add @instana/aws-lambda) 를 실행하여 프로젝트에 @instana/aws-lambda 종속성을 추가하십시오. 그러면 패키지가 node_modules 폴더에 추가되고 package.json 파일에 종속성이 저장됩니다.
2. 환경 변수 INSTANA_ENDPOINT_URL 및 INSTANA_AGENT_KEY 를 필수 값으로 추가하십시오.
3. 핸들러를 수동으로 랩핑섹션에 따라 함수의 코드를 수정하십시오.

핸들러 수동 래핑

자동 줄 바꾸기 핸들러를 사용하지 않거나 사용하지 않으려는 경우, Node.js AWS Lambda 함수의 코드를 약간 수정하여 인스턴스 추적을 사용 가능하게 해야 합니다.

AutoTrace AWS Lambdas절에 설명된 대로 Instana Lambda 계층 및 자동 줄 바꾸기 핸들러를 사용하는 경우에는 이 절에 설명된 코드 수정이 필요하지 않습니다.

웹 팩으로 Lambda 핸들러를 번들화하는 경우, Instana의 코어 패키지가 웹 팩으로 사전 처리되는 것을 지원하지 않으므로 이 방법은 권장되지 않습니다 . AutoTrace AWS Lambdas 접근 방식은 웹 팩을 사용하는 Lambdas에 적합합니다. 대안으로 수동 랩핑을 사용하고 최소한 @instana/aws-lambda 패키지 (또는 모든 종속 항목) 가 웹팩에서 사전 처리되지 않도록 제외할 수 있습니다. Node.js 문서에서 이 섹션 을 참조하십시오. 서버리스 프레임워크의 경우 서버리스 프레임워크 섹션도 참조하십시오.

1. const instana = require('@instana/aws-lambda'); 행을 핸들러 JavaScript 파일의 맨 위에 추가하십시오.
2. instana.wrap() 호출에서 핸들러 함수를 랩하십시오.
3. AWS Lambda에 대한 AutoTrace 인스턴스 문서에 설명된 대로 인스턴스 백엔드에 대한 연결에 대한 환경 변수를 구성하십시오.

다음은 Node.js 기반 AWS Lambda에 사용할 수 있는 서로 다른 핸들러 함수 스타일에 대한 예제 전후의 일부입니다.

exports.handler = async (event, context) => {
  // your code
};

const instana = require('@instana/aws-lambda');

exports.handler = instana.wrap(async (event, context) => {
  // your code
}); // <- don't forget the closing ) for the instana.wrap(

exports.handler = (event, context) => {
  // your code, which returns a promise
};

const instana = require('@instana/aws-lambda');

exports.handler = instana.wrap((event, context) => {
  // your code, which returns a promise
}); // <- don't forget the closing ) for the instana.wrap(

exports.handler = (event, context, callback) => {
  // your code
};

const instana = require('@instana/aws-lambda');

exports.handler = instana.wrap((event, context, callback) => {
  // your code
}); // <- don't forget the closing ) for the instana.wrap(

exports.handler = instana.wrap({
    // ... your configuration, for example:
    tracing: {
      stackTraceLength: 10
    }
  },
  async (event, context) => {
  // your code
});

서버리스 프레임워크와 Instana 추적 통합

serverless.yml 를 편집하여 인스턴스 추적을 Serverless Framework와 통합하십시오. 다음 단계를 따르십시오.

1. 목록에서 계층 ARN 을 복사하고 ARN을 대상 함수 정의의 레이어 섹션 에 추가하십시오.

2. 환경 변수 INSTANA_AGENT_KEY, INSTANA_ENDPOINT_URL 및 LAMBDA_HANDLER를 추가하십시오. 자세한 정보는 Instana AutoTrace 설정을 참조하십시오.

다음 예제를 참조하십시오. serverless.yml

service: service-a

provider:
  name: aws
  runtime: nodejs16.x
  stage: dev
  region: us-east-2

functions:
  with-layer:
    environment:
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:111
    handler: instana-aws-lambda-auto-wrap.handler

service: service-b

provider:
  name: aws
  runtime: nodejs12.x
  stage: dev
  region: us-east-2

plugins:
  - serverless-offline

custom:
  serverless-offline:
    useDocker: true

functions:
  with-serverless-offline:
    environment:
      NODE_PATH: $NODE_PATH:/opt/nodejs/node_modules
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:111
    handler: instana-aws-lambda-auto-wrap.handler

service: service-c

provider:
  name: aws
  runtime: nodejs12.x
  stage: dev
  region: us-east-2

plugins:
  - serverless-webpack

package:
  individually: true

functions:
  with-serverless-webpack:
    environment:
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:110
    handler: instana-aws-lambda-auto-wrap.handler
    entrypoint: src/index.handler

통화 취소 및 잊어버리기

Node.js Lambda 함수에서 fire-and-forget 스타일 호출을 사용하는 경우, 인스턴스는 이를 안정적으로 캡처하도록 보장할 수 없습니다. 화재 및 삭제 호출은 결과를 기다리지 않는 비동기 호출입니다. 예는 다음과 같습니다.

const fetch = require('node-fetch');

exports.handler = async event => {
  fetch('https://example.com/fire-and-forget'); // No await here!

  const response = await fetch('https://example.com/wait-for-me');

  return {
    message: response.text()
  };
}

이 람다 핸들러는 ' node-fetch ' 패키지를 사용하여 두 개의 HTTP 호출을 수행합니다. 두 번째 호출은 async 키워드를 사용하여 호출되므로 실행이 완료될 때까지 대기합니다. 이 호출은 신뢰성 있게 추적될 것이다.

이와 대조적으로 코드는 첫 번째 호출 (fetch('https://example.com/fire-and-forget')) 결과를 기다리지 않습니다. 이 호출은 람다 실행이 완료될 때까지 완료되었을 수 있습니다. 람바 실행이 전체적으로 종료될 때 완료되지 않은 경우에는 호출이 인스턴스 백엔드에 보고되지 않습니다. 인스턴스 UI 에서 해당 추적을 검사하는 경우 "처리 중에 이 추적의 일부 항목에 대한 상위 범위가 누락되었습니다." 라는 경고가 표시될 수 있습니다.

이 예제에서는 비동기/대기 스타일을 사용했지만 유사한 예제도 약속 스타일 및 콜백 스타일 코드에 대해 존재합니다.

SSM 지원

instana-nodejs/@instana/aws-lambda@1.138.0계층의 버전 99에서 사용 가능합니다.

AWS SSM (System Manager) 매개변수 저장소를 통해 인스턴스화 에이전트 키를 제공할 수도 있습니다.

1. 인스턴스 에이전트 키를 SSM 매개변수 저장소에 추가하십시오. 매개변수 이름을 기억하거나 복사하십시오.
2. 환경 변수에서 INSTANA_AGENT_KEY 를 제거하십시오.
3. 복사된 매개변수 이름을 사용하여 환경 변수에 INSTANA_SSM_PARAM_NAME 를 추가하십시오.
4. 매개변수를 다음과 같이 추가한 경우"SecureString", 당신도 설정해야합니다INSTANA_SSM_DECRYPTION=true . "문자열" 유형을 사용한 경우, 추가 변수를 설정할 필요가 없습니다.

환경 변수에서 INSTANA_AGENT_KEY 를 제거하지 않으면 SSM 환경 변수가 무시됩니다.

이전 Node.js 람다 런타임

작성 시, Amazon에서는 Node.js 14, 12및 10을 Lambda 런타임으로 제공합니다. 인스턴스는 이미 AWS (예: 노드 4및 6) 에 의해 분석된 이전 Node.js Lambda 런타임을 지원하지 않습니다. 해당 런타임을 사용하는 Lambda가 여전히 배치되어 있는 경우 원시 인스턴스 추적용으로 구성하기 전에 더 최근의 Node.js Lambda 런타임으로 갱신하십시오. Node.js 8은 이미 수명이 종료되었지만 지금도 지원됩니다.