Next.js 서버사이드/클라이언트 사이드 분산추적/모니터링 툴 elastic-node-apm, elastic-rum 설치 이슈와 해결방법

 

elastic-node-apm 이란 무엇입니까? 

Elastic APM(애플리케이션 성능 모니터링)은 Elasticsearch, Kibana 및 Logstash를 지원하는 회사인 Elastic에서 제공하는 도구입니다. Elastic APM은 개발자가 애플리케이션 성능을 실시간으로 모니터링하고 분석할 수 있도록 설계되었습니다. 

이를 통해 애플리케이션의 다양한 구성 요소 성능을 추적하고, 병목 현상을 식별하고, 문제를 효율적으로 해결할 수 있습니다.
특히 Node.js 애플리케이션에 맞게 조정된 Elastic APM의 일부를 나타냅니다.
트랜잭션 추적, 오류 캡처, 성능 지표 수집 등 Node.js 애플리케이션의 성능을 모니터링하기 위한 계측 및 도구를 제공합니다.

 

 

서버 사이드 모니터링을 위해 elastic-apm-node 를 설치하는 것이며,

클라이언트 사이드 모니터링 하려면 elastic RUM 을 설치해야 합니다 .

Next.js 는 클라이언트 사이드와 서버사이드 가 동시에 존재하므로 둘다 설치해주면 됩니다.

• https://www.elastic.co/guide/en/apm/agent/nodejs/current/nextjs.html

 

클라이언트 사이드 모니터링

클라이언트 사이드 모니터링 하려면 elastic RUM 을 설치해야 합니다 .

elastic-search 의 Logs/Stream 페이지에서 실시간으로 프론트엔드 클라이언트 단의 에러 로그 확인 가능합니다.

상세히 확인하고 싶은 대상 로그의 우측에 나타나는 ... 버튼을 클릭하여 상세 정보를 확인가능합니다.

대상 서비스 이름, 페이지 경로, 접속자 정보 등 상세 정보가 나타나게 됩니다.

 

 

Next.js 에 elastic-rum 설치 방법

elastic-rum-react 의 ApmRouter 컴포넌트는 react-router 를 사용하는 일반 리액트 프로젝트에서 사용할 수 있기 때문에, 
react-router 가 필요없는 Next.js 에서는 별도의 ApmTransaction 컴포넌트롤 만들어서 적용시켰습니다. 

참고로 ApmRouter 대신에 사용할 수 있는withTransaction 라는 것이 있지만, 이것도 react-router 종속성 필요합니다. 

종속성 설치 없이 해결하려면 별도의 ApmTransaction 컴포넌트롤 만들어서 적용시키는게 나은 방법인 듯 합니다.

 

설치 커맨드

yarn add @elastic/apm-rum @elastic/apm-rum-core

 

AppTransaction 컴포넌트 생성 하고 _app.tsx 에서 Component 를 감싸주기

// components/apm/ApmTransaction.tsx
import { useRouter } from 'next/router'
import React, { useEffect, useMemo, type ReactNode } from 'react'
// @ts-ignore
import { afterFrame } from '@elastic/apm-rum-core'
import { ApmBase } from '@elastic/apm-rum'

const ApmTransaction = ({
  children,
  apm,
}: {
  children: ReactNode
  apm: ApmBase
}) => {
  const router = useRouter()

  const transaction = useMemo(() => {
    if (!apm) return
    return apm.startTransaction(router.asPath, 'route-change', {
      managed: true,
      canReuse: true,
    })
  }, [apm, router.asPath])

  useEffect(() => {
    if (!transaction) return
    afterFrame(() => transaction && (transaction as any)?.detectFinish())
    return () => {
      /**
       * Incase the transaction is never ended, we check if the transaction
       * can be closed during unmount phase
       *
       * We call detectFinish instead of forcefully ending the transaction
       * since it could be a redirect route and we might prematurely close
       * the currently running transaction
       */
      transaction && (transaction as any)?.detectFinish()
    }
  }, [transaction])

  return <>{children}</>
}

export default ApmTransaction

 

// pages/_app.tsx
import { init as initApm } from '@elastic/apm-rum'
import ApmTransaction from '@/components/apm/ApmTransaction'

const apm = initApm({
  // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space)
  serviceName: '서비스이름',
  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: 'elastic서버주소입력해주세요',
  distributedTracingOrigins: [
   '교차 출처 요청을 포함하고 싶은 요청 주소를 이곳에 추가'
  ],
})

// ... 이하 생략
// 저는 레이아웃 쓰고 있어서 getLayout 있는것. 없으면 무시해도 무관

  {getLayout(
     <ApmTransaction apm={apm}>
       <Component {...pageProps} />
     </ApmTransaction>,
  )}
  
// ...

 

분산추적 - 교차 출처 요청 활성화 참고 링크

 

 

 

서버사이드 사이드 모니터링

서버 사이드 모니터링을 위해 elastic-apm-node 를 설치해야 합니다.

APM/Services 메뉴에 들어가면 서비스들이 보여지며, 원하는 서비스를 클릭후 Errors 텝을 클릭하면 에러들을 볼 수 있습니다.

 

그리고 상세히 확인하고 싶은 에러를 클릭 후 하단에 Metadata 텝을 클릭하면 어느 페이지에서 어떤 에러가 발생했는지 정말 상세히 확인이 가능합니다.

 

Next.js 에 elastic-node-apm 설치 방법

Get started with Next.js | APM Node.js Agent Reference [4.x] | Elastic

설치 방법은 공식 홈페이지의 설치 가이드를 따라하면 됩니다. 

그러나 설치 이슈 2가지 존재하는데요. 이번 게시물에서는 설치 이슈와 해결 방법에 대해서 중점적으로 설명하려고 합니다.

 

 

이슈와 해결방법

Next.js 13.3.0 버전 이상에서는 계측 지원 중단

• https://github.com/elastic/apm-agent-nodejs/issues/3263
• 해결법 : Next 13.2.X 으로 버전 다운그레이드

next@13.3.0 support · Issue #3263 · elastic/apm-agent-nodejs

 

Next.js 구동 전에 elastic 파일을 시키기 때문에 .env 파일을 사용할 수 없기 때문에 코드에 하드코딩된 key값이 원격 저장소에 그대로 올라가게 되는 이슈

• 해결방법 : Elastic Server Url, SecretToken 값을 Github Action Secret Key 에 추가한 뒤 CI/CD workflow 의 .env 생성 직후 Secert Key 값 가져와서 elastic-apm-node.js 파일을 직접 생성하는 방법으로 해결할 수 있습니다.

 

Next.js 를 standalone mode 로 사용하는 경우 Docker 에서 빌드후 실행했을때 elastic-amp-node/start-next.js 모듈을 찾을 수 없다는 문제 발생하는 이슈

• https://github.com/elastic/apm-agent-nodejs/issues/3342
• Next.js 를 standalone 모드로 빌드시키면 꼭 필요한 최소한의 종속성 포함하여 node_modules 에 추가하므로 빌드 폴더 가벼워지고 도커 이미지 용량 줄어드는 효과 있습니다. 그러나 이 StandAlone 모드 사용할 때 도커에서 elastic-apm-node 찾을 수 없다는 이슈가 발생합니다.
• Next.js 의 standAlone 모드는 프로덕션 빌드시 꼭 필요한 종속성만 node_modules 폴더에 포함시키게 되는데 elastic-amp-node 는 종속성 설치만 했을 뿐이지, 실제로 코드상에 그 어디에도 사용한다고 작성해준 부분이 없어서 필요 없는 종속성 이라고 판단 해버린 것인지.. standAlone 의 node_modules 에 포함되지 않더군요. 그래서 못 찾는 것 같다고 생각됩니다.

로컬에서 도커 테스트 시 커맨드 참고

• docker build --platform linux/arm64/v8 -t test .
• docker run -d -p 3306:3000 --name react-app test
• (삭제시) docker rm <container-name> -f

 

SIGSEGV 오류

• 해결방법 : sharp 패키지를 제거하여 해결했었음. 🤔🤔🤔🤔
  그러나 sharp 가 없으면 빌드 환경에서 이미지 최적화가 안되기 때문에
  추후 0.32.0 버전으로 재설치하였는데 그땐 빌드시 오류 없어졌었음. 뭣 때문인지 명확하지 않음. 현재는 0.32.6 으로 사용중

 

elastic-amp-node/start-next.js 모듈 찾을 수 없음 오류 발생

• 해결방법: 더미 api 에 elastic-apm-node/start-next 를 import 해서 사용함으로써 빌드후 standalone/node_modules 에 start-next.js 파일을 포함시키면 됩니다.

 

아래는 시행착오 과정입니다.

더미 api 에 elastic-apm-node 포함 시키는 것만으로도, Next.js 빌드 후 standAlone 폴더 안의 node_modules 폴더안에 elastic-apm-node 가 포함이 됩니다.

더미 api 에 elastic-apm-node 포함

 

아래와 같이 정확히 start-next 파일을 import 해줘야 start.js, start-next.js 까지 node_modules 에 포함된것 확인했습니다.

Next.js 빌드 후 standAlone 폴더 안의 node_modules 폴더안에 elastic-apm-node 가 들어갑니다

 

DockerFile 에서 마지막줄 경로를 node_modules → /app/node_modules 로 변경 하면 구동 성공합니다.

성공 화면

elastic service 화면