Spring Boot 에이전트 워크로드, Oracle JDBC, 그리고 Oracle AI Database 서버 측 실행에 걸쳐 하나의 연속적인 트레이스 (Trace)를 구축합니다.

데모를 위한 모든 소스 코드, 설정, 스크립트 및 지원 문서는 GitHub의 observability 폴더에서 확인할 수 있습니다.

핵심 요약 (Key Takeaways)

• Oracle AI Database를 사용하면 트레이스 (Trace)가 데이터베이스 경계에서 멈추지 않고 데이터베이스 서버 측 실행까지 계속됩니다.
• Spring Boot와 Micrometer가 애플리케이션 트레이스 컨텍스트 (Trace context)를 생성하며, Oracle JDBC가 데이터베이스 클라이언트 스팬 (Spans)을 추가합니다.
• DBMS_OBSERVABILITY는 Oracle AI Database 서버 측 스팬 (Spans)을 OpenTelemetry 호환 관측성 도구로 내보냅니다. 이 데모에서는 Jaeger를 사용합니다.
• 에이전트 메타데이터인 MODULE, ACTION, CLIENT_IDENTIFIER는 보안 및 감사 상관관계 (Audit correlation)를 위한 기반을 마련합니다.

이 가이드는 에이전틱 (Agentic) 애플리케이션에 대한 실질적인 질문에 답합니다: AI 에이전트 요청으로 시작하여 Spring Boot와 JDBC 계층을 거쳐 Oracle AI Database 내부까지 이어지는 하나의 트레이스 (Trace)를 볼 수 있을까요? 정답은 '예'입니다. Spring Boot, Micrometer, Oracle JDBC 관측성 프로바이더 (Observability providers), 그리고 DBMS_OBSERVABILITY를 사용하면 동일한 요청이 애플리케이션 스팬 (Spans), JDBC 스팬 (Spans), 그리고 Oracle AI Database 서버 측 스팬 (Spans)으로서 모든 OpenTelemetry 호환 관측성 백엔드에 나타날 수 있습니다. 이 가이드에서는 실행이 간단하고 검사가 용이한 Jaeger를 사용하지만, 동일한 시그널을 모든 OpenTelemetry 준수 관측성 도구에서 확인할 수 있습니다.

해당 데이터베이스 내부 스팬 (database-internal span)이 중요한 부분입니다. 일반적인 데이터베이스 관측성 (observability)은 데이터베이스 경계에서 멈춥니다. 즉, 애플리케이션 트레이스 (trace)를 통해 JDBC가 데이터베이스를 기다렸다는 사실은 알 수 있지만, 사용자는 도구를 전환하여 데이터베이스 내부를 수동으로 조사해야 합니다. Oracle AI Database는 트레이스를 연속적으로 유지합니다. 개발자, DevOps 팀, 보안 검토자는 데이터베이스가 실제로 소요한 시간을 확인하고, 이를 데이터베이스 측 증거와 상관관계 (correlate)를 맺을 수 있으며, 성능 프로파일링 (performance profiling), 트러블슈팅 (troubleshooting), 보안 컨텍스트 (security context)를 위해 동일한 트레이스를 사용할 수 있습니다.

비디오 워크스루 및 요약:

주요 커버 다이어그램: AI 에이전트 요청부터 Oracle AI Database 서버 측 실행까지 이어지는 하나의 OpenTelemetry 트레이스.

우리가 구축하고 있는 것

데모 앱은 observability/springboot-oracle-db-otel-demo에 위치합니다. 이는 두 개의 주요 엔드포인트 (endpoint)를 가진 Spring Boot 앱입니다:

여기서 Jaeger는 데모 뷰어이며, 텔레메트리 (telemetry)는 OpenTelemetry 호환 방식입니다.

의도된 트레이스 형태는 다음과 같습니다:

브라우저 또는 curl
  -> Spring Boot HTTP 스팬 (span)
  -> Micrometer 관측 (observation)
...

애플리케이션 및 JDBC 스팬 (spans)은 Java 프로세스에서 흐르고, 데이터베이스 서버 측 스팬 (spans)은 Oracle AI Database에서 흐릅니다. 이 두 스팬은 동일한 OpenTelemetry 컬렉터 (collector)에서 만납니다.

선택된 데이터베이스 서버 측 스팬 (span)은 애플리케이션 요청과 동일한 트레이스 (trace) 내에서 데이터베이스 타이밍 (timing) 및 데이터베이스 측 식별 태그 (identity tags)를 보여줍니다.

데모 페이지는 에이전트 작업 (agent task), 데이터베이스 세션 컨텍스트 (database session context), 데이터베이스 보안 컨텍스트 (database security context), SQL 진단 (SQL diagnostics) 및 트레이스 브릿지 (trace bridge)를 하나로 유지합니다.

예제를 어떻게 설정하고 실행하나요?

데모는 Oracle Database Free, Jaeger, HTTPS 프록시 (proxy) 및 Spring Boot 앱을 실행할 수 있는 충분한 메모리를 갖춘 모든 Linux 환경 또는 VM에서 실행할 수 있습니다. 로컬 데이터베이스 대신 Oracle Cloud의 Autonomous Database를 사용할 수도 있습니다. 중요한 요구 사항은 JDBC 연결성과 HTTPS OTLP 엔드포인트 (endpoint)에 도달할 수 있는 데이터베이스 서버 측 익스포터 (exporter)입니다.

Oracle Database Free 23.26.2.0을 사용한 깨끗한 OCI Linux VM 검증 결과, 숨겨진 KSTRC 인스턴스 파라미터 (parameters)를 설정하지 않고도 예상대로 Spring Boot, Oracle JDBC 및 oracle-db 서버 측 스팬 (spans)이 생성되었습니다. 아래의 일반적인 설정은 문서화된 DBMS_OBSERVABILITY 구성, 도달 가능한 HTTPS OTLP 엔드포인트 (endpoint), 네트워크 ACL 및 데이터베이스 disttrc 트러스트 월렛 (trust wallet)을 사용합니다.

1. Java 25, Maven, Git, Podman, curl, jq, 및 OpenSSL을 설치합니다.
2. Linux에서 Oracle Database Free를 실행하거나, Oracle Cloud에서 Autonomous Database를 프로비저닝합니다.
3. github.com/oracle-devrel/oracle-ai-for-sustainable-dev에서 소스 코드를 클론(Clone)하고 observability 폴더를 사용합니다.
4. OTLP HTTP가 활성화된 상태로 Jaeger를 시작합니다. 샘플 설정에서 Jaeger는 http://127.0.0.1:4318/v1/traces를 통해 애플리케이션 및 JDBC 스팬 (spans)을 수신합니다.
5. 데이터베이스 서버 측 내보내기 (export)를 위해 Jaeger의 OTLP 엔드포인트 (endpoint) 앞에 작은 HTTPS 프록시를 배치합니다. 샘플에서는 NGINX를 otel-tls-proxy로 사용하여 https://otel-tls-proxy:4318/v1/traces를 Jaeger의 http://oracle-db-otel-jaeger:4318/v1/traces로 전달합니다.
6. Oracle AI Database가 서버 측 스팬 (spans)을 HTTPS OTLP 엔드포인트로 푸시할 수 있도록 DBMS_OBSERVABILITY, 네트워크 ACL, 그리고 데이터베이스 월렛/트러스트 경로 (wallet/trust path)를 구성합니다.
7. Spring Boot 앱을 구성, 빌드 및 실행한 다음, 에이전트 작업 뷰 (agent task view)를 열거나 JSON 엔드포인트 (endpoint)를 호출하여 트레이스 (trace)를 생성합니다.

sudo dnf install -y podman git java-25-openjdk java-25-openjdk-devel maven jq curl openssl
export JAVA_HOME=/usr/lib/jvm/java-25-openjdk
export PATH="$JAVA_HOME/bin:$PATH"
...

데이터베이스 자격 증명 (credentials) 및 런타임 엔드포인트 (runtime endpoints)는 저장소(repository) 외부에 유지하십시오:

export DB_URL='jdbc:oracle:thin:@//127.0.0.1:1521/FREEPDB1'
export DB_USERNAME='FINANCIAL'
export DB_PASSWORD='<app-user-password>'
...

java -jar target/springboot-oracle-db-otel-demo-0.0.1-SNAPSHOT.jar

curl -sS http://127.0.0.1:8080/trace/roundtrip | jq .
...

통합된 브라우저 뷰 (browser view)를 보려면 다음을 여십시오:

Maven 의존성 (Dependencies) 및 Oracle JDBC 관측성 프로바이더 (Observability Provider)

이 앱은 Java 25, Maven Central의 Oracle JDBC 23.26 라인, 게시된 Maven Central의 ojdbc-provider-observability 아티팩트 (artifact), 그리고 Oracle JDBC 17 프로덕션 의존성 (production dependency)을 사용합니다.

<properties>
  <java.version>25</java.version>
  <oracle.jdbc.version>23.26.2.0.0</oracle.jdbc.version>
...

Spring Boot Actuator가 관측 인프라 (observation infrastructure)를 생성하고, Micrometer가 이러한 관측 데이터 (observations)를 OpenTelemetry로 연결하며, OTLP exporter가 span을 collector로 전송합니다. oracle-database.version 속성은 Oracle JDBC, UCP, wallet/security 및 관련 전이적 아티팩트 (transitive artifacts)를 23.26.2.0.0 버전으로 일치하게 유지합니다.

Oracle JDBC 관측성 제공자 (observability provider)는 JDBC 드라이버의 TraceEventListener 인터페이스를 구현하고 JDBC 이벤트를 OpenTelemetry로 발행합니다. 이러한 이벤트에는 데이터베이스 라운드 트립 (round trips) 및 연결 동작이 포함되며, 연결 ID (connection id), 데이터베이스 작업 (database operation), 데이터베이스 사용자 (database user), 테넌트 (tenant), SQL ID와 같은 속성 (attributes)이 포함됩니다. SQL 텍스트 및 연결 세부 정보는 민감한 정보로 취급되어 명시적으로 활성화하지 않는 한 기본적으로 비활성화됩니다.

Spring Boot 및 JDBC Span은 어떻게 생성되나요?

Oracle JDBC OpenTelemetry 확장 기능은 애플리케이션에 이미 활성화된 OpenTelemetry 컨텍스트 (context)가 있다고 가정합니다. 이 확장 기능들은 스스로 루트 애플리케이션 트레이스 (root application trace)를 생성하지 않습니다. 이 데모에서는 Spring Boot Actuator와 Micrometer가 HTTP 및 애플리케이션 관측 데이터를 제공하며, Oracle JDBC 제공자가 데이터베이스 라운드 트립과 같은 JDBC 드라이버 이벤트에 대한 자식 스팬 (child spans)을 추가합니다. 또한 제공자는 트레이스 컨텍스트를 Oracle AI Database로 전파하여, 데이터베이스가 서버 측 스팬 (server-side span)을 동일한 트레이스로 내보낼 수 있도록 합니다.

애플리케이션 인스트루멘테이션 (instrumentation)을 직접 추가하고 싶지 않다면, 코드 수정이 필요 없는 Java 인스트루멘테이션을 위해 OpenTelemetry Java agent를 사용하십시오. 그러면 Oracle JDBC 확장 기능이 현재 애플리케이션 스팬의 자식으로 데이터베이스 라운드 트립 스팬을 추가하고 해당 컨텍스트를 서버로 전파할 수 있습니다.

Spring Boot는 애플리케이션 및 JDBC 스팬을 OTLP HTTP를 통해 전송합니다. 데모에서는 이를 Jaeger로 전송하지만, 동일한 OpenTelemetry 시그널 (signal)은 모든 OpenTelemetry 호환 관측 플랫폼 (observability platform)에서 수집될 수 있습니다. Oracle JDBC 제공자 속성을 통해 JDBC 트레이스 리스너 (trace listener)를 활성화하고 collector에서 Java 서비스를 식별할 수 있습니다.

spring:
  application:
    name: springboot-oracle-db-otel-demo
...

데이터베이스 서버 측 스팬 (Spans)은 어떻게 내보내나요?

데이터베이스 서버 측 익스포터 (exporter)는 도달 가능한 HTTPS OTLP 엔드포인트 (endpoint)가 필요합니다. 검증된 Linux 데모는 4318 포트에서 OTLP HTTP를 수용하는 Jaeger를 사용하며, 데이터베이스 서버 측 내보내기를 위해 그 앞에 작은 HTTPS 프록시 (proxy)를 배치합니다. 샘플에서 해당 프록시는 신뢰할 수 있는 로컬 인증서를 사용하는 NGINX입니다:

Oracle AI Database -> https://otel-tls-proxy:4318/v1/traces
otel-tls-proxy -> http://oracle-db-otel-jaeger:4318/v1/traces

OTLP 엔드포인트를 변경하여 Jaeger를 다른 OpenTelemetry 호환 컬렉터 (collector) 또는 백엔드 (backend)로 교체할 수 있습니다. 중요한 요구 사항은 Oracle AI Database가 서버 측 트레이스 (trace) 내보내기를 위해 HTTPS를 통해 해당 엔드포인트에 도달할 수 있어야 한다는 점입니다.

DBMS_OBSERVABILITY로 데이터베이스를 구성하고, SQL 세션을 실행하는 사용자에게 네트워크 ACL 액세스 권한을 부여하며, 분산 트레이스 익스포터 (distributed trace exporter)가 예상하는 위치인 WALLET_ROOT/<PDB_GUID>/disttrc에 신뢰할 수 있는 월렛 (wallet)을 배치하십시오.

begin
  dbms_observability.add_endpoint(
    endpoint_type => dbms_observability.otel_traces,
...

Oracle Database Free 23.26.2.0에서 수행한 깔끔한 검증 실행 결과, 문서화된 DBMS_OBSERVABILITY 엔드포인트 설정, HTTPS OTLP 프록시, 네트워크 ACL, 그리고 WALLET_ROOT/<PDB_GUID>/disttrc 신뢰 월렛만으로 데이터베이스 서버 측 스팬 (spans)을 처리하기에 충분함을 확인했습니다. 이전의 로컬 진단 실행에서는 내보내기 실패를 디버깅할 때 숨겨진 KSTRC 파라미터 (parameters)를 사용했지만, 해당 설정은 일반적인 데모 설정의 일부가 아닙니다.

JDBC는 트레이스 컨텍스트 (Trace Context)를 어떻게 전파하나요?

애플리케이션은 공개된 ojdbc-provider-observability 의존성 (dependency)을 사용합니다. 현재는 트레이스를 활성화하기 전에 서버 텔레메트리 (telemetry) 상태 변경을 강제해야 하므로, 드라이버가 텔레메트리 상태를 데이터베이스에 함께 전달 (piggybacks)합니다.

EnumSet<OracleConnection.ServerTelemetry> requestedTelemetry =
    EnumSet.of(OracleConnection.ServerTelemetry.Traces);

...

데이터베이스 스팬 (Database Span)을 어떻게 유용하게 만드나요?

일반적인 DB Server 스팬은 트레이스(trace)가 데이터베이스로 넘어갔음을 증명하지만, 이 데모에서는 SQL이 실행되기 전에 데이터베이스 세션 필드(session fields)를 설정함으로써 이를 더욱 유용하게 만듭니다. 애플리케이션은 이 메타데이터를 위해 Oracle JDBC 엔드 투 엔드 메트릭 API (end-to-end metrics API)를 사용하므로, MODULE, ACTION, CLIENT_IDENTIFIER를 설정하기 위해 별도의 PL/SQL 라운드 트립 (round trip)을 수행할 필요가 없습니다.

String[] metrics = new String[OracleConnection.END_TO_END_STATE_INDEX_MAX];
metrics[OracleConnection.END_TO_END_MODULE_INDEX] = "agent:claims-investigator-agent";
metrics[OracleConnection.END_TO_END_ACTION_INDEX] = "agent-workload-query";
...