관찰성은 실행 중 워크플로의 내부 상태 및 동작에 대한 인사이트를 제공합니다. 여기에는 워크플로를 모니터링하고 디버그하는 데 도움이 되는 로깅, 메트릭 및 추적 기능이 포함됩니다.
팁 (조언)
관찰성은 프레임워크 전체의 기능이며 워크플로에 국한되지 않습니다. 자세한 내용은 관찰 기능을 참조하세요.
에이전트 프레임워크 워크플로는 표준 GenAI 원격 분석 외에도 추가 범위, 로그 및 메트릭을 내보내 워크플로 실행에 대한 심층적인 인사이트를 제공합니다. 이러한 관찰 기능은 개발자가 메시지 흐름, 실행기의 성능 및 발생할 수 있는 오류를 이해하는 데 도움이 됩니다.
옵저버빌리티 활성화
애플리케이션에서 관찰 가능성을 사용하도록 설정하는 방법에 대한 지침은 관찰 가능성 사용(Enabling Observability )을 참조하세요.
애플리케이션에서 관찰 가능성을 사용하도록 설정하는 방법에 대한 지침은 관찰 가능성 사용(Enabling Observability )을 참조하세요.
워크플로 범위
워크플로 실행 중에 다음 범위가 내보내집니다.
| 범위 이름 | Description |
|---|---|
workflow.build |
각 워크플로 빌드에 대해 내보냅니다. |
workflow.session |
워크플로 실행의 전체 수명(시작부터 중지 또는 오류까지)을 나타내는 외부 범위입니다. |
workflow_invoke |
워크플로 세션 내의 각 입력-중지 주기에 대해 내보냅니다. |
executor.process {executor_id} |
메시지를 처리하는 각 실행자에 대해 내보냅니다. 실행기 ID는 범위 이름에 추가됩니다. |
edge_group.process |
메시지를 처리하는 각 에지 그룹에 대해 내보냅니다. |
message.send |
실행기에서 다른 실행기로 전송된 각 메시지에 대해 내보내집니다. |
워크플로 실행 중에 다음 범위가 내보내집니다.
| 범위 이름 | Description |
|---|---|
workflow.build |
각 워크플로 빌드에 대해 내보냅니다. |
workflow.run |
각 워크플로 실행에 대해 내보냅니다. |
executor.process {executor_id} |
메시지를 처리하는 각 실행자에 대해 내보냅니다. 실행기 ID는 범위 이름에 추가됩니다. |
edge_group.process {edge_group_type} |
메시지를 처리하는 각 에지 그룹에 대해 내보냅니다. 에지 그룹 유형이 범위 이름에 추가됩니다. |
message.send |
실행기에서 다른 실행기로 전송된 각 메시지에 대해 내보내집니다. |
범위 특성
스팬은 작업에 대한 추가 컨텍스트를 제공하는 특성을 전달합니다. 워크플로 범위에서 설정되는 특성은 다음과 같습니다.
| 특성 | 범위(들) | Description |
|---|---|---|
workflow.id |
workflow.build, workflow.session |
워크플로의 고유 식별자입니다. |
workflow.name |
workflow.session |
워크플로의 이름입니다. |
workflow.description |
workflow.session |
워크플로 설명입니다. |
workflow.definition |
workflow.build |
워크플로 그래프의 JSON 정의입니다. |
session.id |
workflow.session |
고유한 세션 식별자입니다. |
executor.id |
executor.process |
실행기의 고유 식별자입니다. |
executor.type |
executor.process |
실행기의 형식 이름입니다. |
executor.input |
executor.process |
입력 메시지입니다. 중요한 데이터를 사용하는 경우에만 설정합니다. |
executor.output |
executor.process |
실행기의 출력입니다. 중요한 데이터를 사용하는 경우에만 설정합니다. |
message.type |
executor.process, message.send |
메시지의 형식 이름입니다. |
message.content |
message.send |
메시지의 내용입니다. 중요한 데이터를 사용하는 경우에만 설정합니다. |
message.source_id |
message.send |
메시지를 보낸 실행기의 ID입니다. |
message.target_id |
message.send |
지정된 경우 대상 실행기의 ID입니다. |
edge_group.type |
edge_group.process |
에지 그룹의 유형입니다. |
edge_group.delivered |
edge_group.process |
메시지가 배달되었는지 여부(불리언)입니다. |
edge_group.delivery_status |
edge_group.process |
배달 결과( Edge 그룹 배달 상태 참조). |
error.type |
오류에 대한 모든 범위 | 예외 형식 이름입니다. |
| 특성 | 범위(들) | Description |
|---|---|---|
workflow.id |
workflow.build, workflow.run |
워크플로의 고유 식별자입니다. |
workflow.name |
workflow.run |
워크플로의 이름입니다. |
workflow.description |
workflow.run |
워크플로 설명입니다. |
workflow.definition |
workflow.build |
워크플로 그래프의 JSON 정의입니다. |
workflow_builder.name |
workflow.build |
워크플로 작성기의 이름입니다. |
workflow_builder.description |
workflow.build |
워크플로 작성기의 설명입니다. |
executor.id |
executor.process |
실행기의 고유 식별자입니다. |
executor.type |
executor.process |
실행기의 형식 이름입니다. |
message.type |
executor.process, message.send |
메시지의 형식 이름입니다. |
message.payload_type |
executor.process |
메시지 페이로드의 데이터 형식입니다. |
message.destination_executor_id |
message.send |
지정된 경우 대상 실행기의 ID입니다. |
message.source_id |
edge_group.process |
메시지를 보낸 실행기의 ID입니다. |
message.target_id |
edge_group.process |
지정된 경우 대상 실행기의 ID입니다. |
edge_group.type |
edge_group.process |
에지 그룹의 유형입니다. |
edge_group.id |
edge_group.process |
에지 그룹의 고유 식별자입니다. |
edge_group.delivered |
edge_group.process |
메시지가 배달되었는지 여부(불리언)입니다. |
edge_group.delivery_status |
edge_group.process |
배달 결과( Edge 그룹 배달 상태 참조). |
스팬 이벤트
범위 이벤트는 범위에 연결된 구조적 로그 항목으로, 각 범위 내에서 중요한 순간의 타임라인을 제공합니다.
| 이벤트 이름 | 범위(들) | Description |
|---|---|---|
build.started |
workflow.build |
빌드 프로세스가 시작될 때 내보냅니다. |
build.validation_completed |
workflow.build |
빌드 유효성 검사가 통과될 때 내보냅니다. |
build.completed |
workflow.build |
빌드가 성공적으로 완료되면 내보냅니다. |
build.error |
workflow.build |
빌드가 실패할 때 내보냅니다. |
session.started |
workflow.session |
워크플로 세션이 시작될 때 내보냅니다. |
session.completed |
workflow.session |
워크플로 세션이 완료될 때 내보냅니다. |
session.error |
workflow.session |
워크플로 세션에 오류가 발생할 때 내보냅니다. |
workflow.started |
workflow_invoke |
워크플로 호출이 시작될 때 내보냅니다. |
workflow.completed |
workflow_invoke |
워크플로 호출이 완료될 때 내보냅니다. |
workflow.error |
workflow_invoke |
워크플로 호출에 오류가 발생할 때 내보냅니다. |
| 이벤트 이름 | 범위(들) | Description |
|---|---|---|
build.started |
workflow.build |
빌드 프로세스가 시작될 때 내보냅니다. |
build.validation_completed |
workflow.build |
빌드 유효성 검사가 통과될 때 내보냅니다. |
build.completed |
workflow.build |
빌드가 성공적으로 완료되면 내보냅니다. |
build.error |
workflow.build |
빌드가 실패할 때 내보냅니다. |
workflow.started |
workflow.run |
워크플로 실행이 시작될 때 내보냅니다. |
workflow.completed |
workflow.run |
워크플로 실행이 완료될 때 내보냅니다. |
workflow.error |
workflow.run |
워크플로 실행 시 오류가 발생할 때 내보냅니다. |
범위 간 연결
실행기가 다른 실행기로 message.send 메시지를 보내면 message.send span은 span의 자식으로 생성됩니다. 실행이 중첩되지 않으므로, 대상 실행기의 executor.process 범위는 message.send 범위의 자식이 아닙니다. 대신 대상 executor.process 실행기의 범위는 원본 실행기의 범위에 연결message.send 됩니다. 이 연결은 중첩된 호출 계층 구조를 의미하지 않고 워크플로 실행을 통해 추적 가능한 경로를 만듭니다.
인과 관계 추적을 위해 edge_group.process 원본 message.send 범위에 연결된 범위에 동일한 연결 방법이 적용됩니다. 이는 여러 원본 범위가 단일 처리 범위에 영향을 주는 팬인 시나리오를 지원합니다.
Edge 그룹 배달 상태
에지 그룹 처리 범위에는 각 에지 그룹을 통한 메시지 라우팅의 결과를 나타내는 배달 상태 특성이 포함됩니다. 특성은 edge_group.delivery_status 다음 값 중 하나로 설정됩니다.
| 상태 | Description |
|---|---|
delivered |
메시지가 대상 실행기로 배달되었습니다. |
dropped type mismatch |
대상 실행기는 메시지 유형을 처리할 수 없습니다. |
dropped target mismatch |
메시지가 이 에지와 일치하지 않는 대상을 지정했습니다. |
dropped condition false |
false로 평가된 에지 라우팅 조건입니다. |
exception |
에지 처리 중에 예외가 발생했습니다. |
buffered |
메시지가 버퍼링되어 추가 메시지(fan-in)를 기다리고 있습니다. |
부울 특성은 edge_group.delivered 메시지가 성공적으로 배달되었는지 여부를 빠르게 확인합니다.
원격 분석 구성
워크플로 작성기에서 확장 메서드를 WithOpenTelemetry 통해 워크플로 원격 분석을 사용하도록 설정할 수 있습니다.
WorkflowTelemetryOptions 클래스는 어떤 범위를 내보낼지에 대한 세밀한 제어를 제공합니다.
| Option | 기본값 | Description |
|---|---|---|
EnableSensitiveData |
false |
범위 특성에 원시 입력, 출력 및 메시지 콘텐츠를 포함합니다. |
DisableWorkflowBuild |
false |
workflow.build 범위를 비활성화합니다. |
DisableWorkflowRun |
false |
비활성화 workflow.session 및 workflow_invoke 범위. |
DisableExecutorProcess |
false |
executor.process 범위를 비활성화합니다. |
DisableEdgeGroupProcess |
false |
edge_group.process 범위를 비활성화합니다. |
DisableMessageSend |
false |
message.send 범위를 비활성화합니다. |
경고
중요한 데이터를 사용하도록 설정하면 원시 메시지 콘텐츠, 실행기 입력 및 실행기 출력이 원격 분석에 포함됩니다. 원격 분석 데이터가 적절하게 보호되는 보안 환경에서만 사용하도록 설정합니다.
워크플로 원격 분석은 전역 enable_instrumentation() 함수를 통해 사용하도록 설정됩니다. 계측을 사용하도록 설정하면 모든 워크플로 범위가 자동으로 내보내집니다. 이 함수를 configure_otel_providers() 사용하여 추적, 메트릭 및 로그에 대한 내보내기를 설정할 수 있습니다.
경고
원격 분석 파이프라인 구성을 검토하여 추적을 내보낼 때 중요한 데이터가 적절하게 보호되는지 확인합니다.