> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickStack용 AWS Lambda - ClickHouse 관측성 스택

# AWS Lambda

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>이 가이드에서 통합하는 항목:</span>
      {supported.includes("logs") && <span style={pillStyle}>로그</span>}
      {supported.includes("metrics") && <span style={pillStyle}>메트릭</span>}
      {supported.includes("traces") && <span style={pillStyle}>트레이스</span>}
    </div>;
};

<ClickStackIntegrates signals={['logs', 'metrics', 'traces']} />

<h2 id="installing-the-otel-lambda-layers">
  OpenTelemetry Lambda 레이어 설치
</h2>

OpenTelemetry 프로젝트는 다음과 같은 용도로 별도의 Lambda 레이어를 제공합니다.

1. OpenTelemetry 자동 계측을 사용하여 Lambda 함수 코드를 자동으로 계측합니다.
2. 수집된 로그, 메트릭, 트레이스를 ClickStack으로 전달합니다.

<h3 id="adding-language-specific-auto-instrumentation">
  언어별 자동 계측 레이어 추가
</h3>

언어별 자동 계측 Lambda 레이어는 해당 언어용 OpenTelemetry 자동 계측 패키지를 사용해 Lambda 함수 코드를 자동으로 계측합니다.

각 언어와 리전마다 고유한 레이어 ARN이 있습니다.

Lambda가 이미 OpenTelemetry SDK로 계측되어 있다면 이 단계는 건너뛰어도 됩니다.

**시작하려면**:

1. Layers 섹션에서 "Add a layer"를 클릭합니다
2. ARN 지정 옵션을 선택한 다음, 언어에 맞는 올바른 ARN을 선택합니다. `<region>`은 사용하는 리전(예: `us-east-2`)으로 바꿔야 합니다:

<Tabs>
  <Tab title="Javascript">
    ```shell theme={null}
    arn:aws:lambda:<region>:184161586896:layer:opentelemetry-nodejs-0_7_0:1
    ```
  </Tab>

  <Tab title="Python">
    ```shell copy theme={null}
    arn:aws:lambda:<region>:184161586896:layer:opentelemetry-python-0_7_0:1
    ```
  </Tab>

  <Tab title="Java">
    ```shell copy theme={null}
    arn:aws:lambda:<region>:184161586896:layer:opentelemetry-javaagent-0_6_0:1
    ```
  </Tab>

  <Tab title="Ruby">
    ```shell copy theme={null}
    arn:aws:lambda:<region>:184161586896:layer:opentelemetry-ruby-0_1_0:1
    ```
  </Tab>
</Tabs>

*레이어의 최신 릴리스는 [OpenTelemetry Lambda Layers GitHub 리포지토리](https://github.com/open-telemetry/opentelemetry-lambda/releases)에서 확인할 수 있습니다.*

3. Lambda 함수의 "Configuration" > "Environment variables"에서 다음 환경 변수를 구성합니다.

<Tabs>
  <Tab title="Javascript">
    ```shell theme={null}
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
    AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
    OTEL_PROPAGATORS=tracecontext
    OTEL_TRACES_SAMPLER=always_on
    ```
  </Tab>

  <Tab title="Python">
    ```shell theme={null}
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
    AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
    OTEL_PROPAGATORS=tracecontext
    OTEL_TRACES_SAMPLER=always_on
    ```
  </Tab>

  <Tab title="Java">
    ```shell theme={null}
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
    AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
    OTEL_PROPAGATORS=tracecontext
    OTEL_TRACES_SAMPLER=always_on
    ```
  </Tab>

  <Tab title="Ruby">
    ```shell theme={null}
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
    AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
    OTEL_PROPAGATORS=tracecontext
    OTEL_TRACES_SAMPLER=always_on
    ```
  </Tab>
</Tabs>

<h3 id="installing-the-otel-collector-layer">
  OpenTelemetry collector 레이어 설치
</h3>

collector 레이어를 사용하면 exporter 지연 시간으로 인한 응답 시간 영향 없이 Lambda 함수에서 ClickStack으로 로그, 메트릭, 트레이스를 전달할 수 있습니다.

**collector 레이어를 설치하려면**:

1. Layers 섹션에서 "Add a layer"를 클릭합니다.
2. "Specify an ARN"을 선택하고 아키텍처에 맞는 ARN을 선택합니다. `<region>`은 사용 중인 리전(예: `us-east-2`)으로 바꾸십시오.

<Tabs>
  <Tab title="x86_64">
    ```shell theme={null}
    arn:aws:lambda:<region>:184161586896:layer:opentelemetry-collector-amd64-0_8_0:1
    ```
  </Tab>

  <Tab title="arm64">
    ```shell theme={null}
    arn:aws:lambda:<region>:184161586896:layer:opentelemetry-collector-arm64-0_8_0:1
    ```
  </Tab>
</Tabs>

3. collector가 ClickStack으로 전송하도록 구성하려면 다음 `collector.yaml` 파일을 프로젝트에 추가합니다.

<Tabs>
  <Tab title="Managed ClickStack">
    ```yaml theme={null}
    # collector.yaml
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 'localhost:4317'
          http:
            endpoint: 'localhost:4318'

    processors:
      batch:
      decouple:

    exporters:
      otlphttp:
        endpoint: "<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>"
        compression: gzip

    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp]
        metrics:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp]
        logs:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp]
    ```
  </Tab>

  <Tab title="ClickStack Open Source">
    ```yaml theme={null}
    # collector.yaml
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 'localhost:4317'
          http:
            endpoint: 'localhost:4318'

    processors:
      batch:
      decouple:

    exporters:
      otlphttp:
        endpoint: "<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>"
        headers:
          authorization: <YOUR_INGESTION_API_KEY>
        compression: gzip

    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp]
        metrics:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp]
        logs:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp]
    ```
  </Tab>
</Tabs>

4. 다음 환경 변수를 추가합니다.

```shell theme={null}
OPENTELEMETRY_COLLECTOR_CONFIG_FILE=/var/task/collector.yaml
```

<h2 id="checking-the-installation">
  설치 확인
</h2>

레이어를 배포한 후에는 Lambda 함수에서 자동으로 수집된 트레이스를
HyperDX에서 확인할 수 있어야 합니다. `decouple` 및 `batching`
프로세서로 인해 텔레메트리 수집이 지연될 수 있으므로, 트레이스가
표시되기까지 시간이 걸릴 수 있습니다. 사용자 지정 로그나 메트릭을 내보내려면 언어별
OpenTelemetry SDK를 사용해 코드를 계측해야 합니다.

<h2 id="troubleshoting">
  문제 해결
</h2>

<h3 id="custom-instrumentation-not-sending">
  사용자 지정 계측이 전송되지 않음
</h3>

수동으로 정의한 트레이스나 기타 텔레메트리가 표시되지 않는다면,
호환되지 않는 버전의 OpenTelemetry API 패키지를 사용하고 있을 수 있습니다. 사용 중인
OpenTelemetry API 패키지 버전이 AWS Lambda에 포함된 버전과 같거나
그보다 낮은 버전인지 확인하십시오.

<h3 id="enabling-sdk-debug-logs">
  SDK 디버그 로그 활성화
</h3>

OpenTelemetry SDK의 디버그 로그를 활성화하려면 `OTEL_LOG_LEVEL` 환경 변수를 `DEBUG`로 설정하세요. 이렇게 하면
자동 계측 레이어가 애플리케이션에 올바르게 계측을 적용하고 있는지 확인하는 데 도움이 됩니다.

<h3 id="enabling-collector-debug-logs">
  collector 디버그 로그 활성화
</h3>

collector 문제를 디버깅하려면 collector 설정 파일을 수정하여 `logging` exporter를 추가하고, 텔레메트리 로그 수준을 `debug`로 설정해 collector Lambda layer에서 더 자세한 로그가 출력되도록 할 수 있습니다.

<Tabs>
  <Tab title="Managed ClickStack">
    ```yaml theme={null}
    # collector.yaml
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 'localhost:4317'
          http:
            endpoint: 'localhost:4318'

    exporters:
      logging:
        verbosity: detailed
      otlphttp:
        endpoint: "<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>"
        compression: gzip

    service:
      telemetry:
        logs:
          level: "debug"
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp, logging]
        metrics:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp, logging]
        logs:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp, logging]
    ```
  </Tab>

  <Tab title="ClickStack Open Source">
    ```yaml theme={null}
    # collector.yaml
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 'localhost:4317'
          http:
            endpoint: 'localhost:4318'

    exporters:
      logging:
        verbosity: detailed
      otlphttp:
        endpoint: "<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>"
        headers:
          authorization: <YOUR_INGESTION_API_KEY>
        compression: gzip

    service:
      telemetry:
        logs:
          level: "debug"
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp, logging]
        metrics:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp, logging]
        logs:
          receivers: [otlp]
          processors: [batch, decouple]
          exporters: [otlphttp, logging]
    ```
  </Tab>
</Tabs>