콘텐츠로 이동
≡

Administrator

Developer

Tools

External Tools

1. Log Analyzer 소개#

이 장에서는 Log Analyzer의 개념과 기본적인 사용 방법을 설명한다.

Log Analyzer#

Log Analyzer는 DBMS의 Active Log를 기반으로 DML 관련 트랜잭션의 이력을 제공하는 DBMS 내의 모듈, 이 모듈과 통신으로 연결된 외부 모듈, 그리고 사용자가 XLog를 사용하기 위해 제공되는 API의 집합이다.

Log Analyzer는 Altibase DBMS와 타사 DBMS의 연동 또는 DBMS 내부의 변경 사항을 DBMS 외부에서 감지 및 처리 등의 용도로 사용할 수 있다.

용어 및 개념#

XLog#

XLog는 물리적 로그를 논리적인 형태로 변형시킨 로그이다.

사용자가 얻는 DML 관련 트랜잭션의 이력이 XLog이다.

XLog Sender#

XLog Sender는 Active Log를 분석하여 XLog를 생성하고 XLog Collector에게 전달하는 모듈이다.

XLog Sender는 Handshake 및 XLog 송신을 능동적으로 수행한다.

XLog Collector#

XLog Collector는 XLog Sender으로부터 Meta 정보 및 XLog를 수신하는 모듈이다.

XLog Collector는 Meta 정보, XLog Queue, Trasaction Table, XLog Pool 등을 가지며, Log Analysis API를 통해 호출된다.

Log Analysis API#

Log Analysis API는 XLog와 이를 해석할 수 있는 Meta 정보를 제공하는 API이다.

Handshake#

Handshake는 XLog Sender와 XLog Collector가 XLog를 송수신하기 전에 Protocol Version, Meta 정보 등을 확인하는 작업이다.

XLog Queue#

XLog Queue는 사용자가 얻기 전의 가용한 XLog를 보관하는 곳이다.

XLog Pool#

XLog Pool은 XLog에 할당될 메모리를 보관하는 곳이다.

XLog Pool은 XLog에 할당될 메모리를 재사용하고 과다한 메모리 사용을 방지하기 위해 존재한다.

Transaction Table#

Transaction Table은 Transaction의 상태와 추가적인 정보를 보관하는 곳이다.

Restart SN#

Restart SN은 XLog Sender가 재시작될 때 읽기 시작할 Active Log의 SN이다.

SN#

SN(Sequence Number)은 로그 레코드의 식별 번호이다.

Replication#

Replication은 한 DBMS의 데이터를 다른 DBMS에 복제하는 기능이다.

Replication SYNC#

Replication SYNC는 지역 서버 Replication Table들의 모든 레코드를 원격 서버로 전송하는 기능이다.

Active Log를 기반으로 Replication을 시작하기 전에, Replication Table의 내용을 일치시키기 위해 사용한다.

Log Analyzer의 동작 방식#

XLog Sender는 DBMS 내에 존재하며, Active Log로 XLog를 만들고 XLog와 Meta 정보를 XLog Collector에게 전송한다. XLog Collector는 사용자의 애플리케이션 내에 존재하며, Log Analysis API를 통해 사용자에게 XLog와 메타 정보를 제공한다.

Log Analysis API를 호출에 실패하면, 오류 원인에 따라 적절한 조치를 취해야 한다. 가장 최근의 오류 정보를 보관하는 곳이 Error Manager이다. 또한 문제 추적을 위해 Log Manager를 제공한다. Log Manager는 간단한 추적 정보와 오류 정보를 Log Manager생성시 지정한 로그 파일에 기록한다.

전체 구조를 그림으로 나타내면 아래와 같다.

[그림 1‑1] Log Analyzer의 구조

사용자는 Log Analysis API를 사용하여 XLog Collector에서 메타 정보와 XLog를 얻는다. 메타 정보는 Handshake 시에 XLog Sender에서 수신하며, 다음 Handshake 전까지 유효하다.

XLog Collector 내에서 메타 정보와 XLog가 이동하는 경로는 아래와 같다.

  1. XLog Pool에서 XLog의 메모리를 얻는다.

  2. XLogCollector는 XLog Sender로부터 XLog를 구성하는 데이터를 수신하여 XLog를 만든다.

  3. XLog는 XLog Queue에 추가되고, 사용자가 Log Analysis API를 사용해서 이를 얻을 수 있다.
    Commit 순서로 Transaction의 XLog를 얻을 경우, XLog Queue에 XLog를 추가하기 전에 Transaction Table에 임시 보관한다.

  4. 사용이 끝난 XLog에 할당된 의 메모리는 XLog Pool에 반환한다.

Meta 정보와 XLog가 XLog Collector에서 이동하는 경로를 그림으로 나타내면 아래와 같다.

[그림 1‑2] XLog Collector의 구조

Log Analyzer의 특징#

XLog Sender는 Replication 모듈을 사용#

XLog Sender는 Replicaton과 거의 동일한 SQL를 사용하여 관리되며, 이중화(Replication)의 속성이 적용된다.

이중화에 대한 자세한 내용은 Replication Manual을 참고한다.

Commit 순서로 Transaction의 XLog 얻기 지원#

XLog Collector를 생성할 때, Commit 순서로 트랜잭션의 XLog 얻기 여부를 지정할 수 있다. Commit 순서로 트랜잭션의 XLog 얻기를 지정하면 아래와 같은 사항이 적용된다.

  • COMMIT XLog가 수신된 후에 해당 트랜잭션의 XLog를 얻을 수 있다.
    Savepoint 관련 XLog는 필요하지 않기 때문에 제공하지 않는다.

  • 롤백된 Transaction의 XLog는 얻을 수 없다.

XLog를 전송하는 방법으로 TCP와 UNIX Domain socket을 지원#

  • UNIX Domain socket은 XLog Sender와 XLog Collector가 같은 장비에 있고, OS가 UNIX 또는 LINUX일 때만 사용할 수 있다.

  • 하나의 XLog Sender에서는 한 종류의 Socket Type만 사용할 수 있다.

ODBC C 값으로 변환을 지원#

Altibase 내부 데이터를 대응하는 ODBC C 데이터 타입으로 변환하는 것을 지원한다.

Log Analyzer 제한 사항#

XLog Sender는 Replication 모듈을 사용하므로, 기본적으로 아래와 같은 제한 사항이 적용된다.

  • SYS 사용자만 XLog Sender 를 구동할 수 있다.

  • 분석 대상을 지정하는 단위는 Table이다.

  • 분석 대상 Table에는 반드시 Primary Key가 존재해야 한다.

  • 분석 대상 Table의 Primary Key를 구성하는 컬럼의 데이터는 수정할 수 없다.
    Primary Key를 구성하는 컬럼에 대한 INSERT와 DELETE는 가능하다.

  • 분석 대상 Table에 대한 DDL을 수행할 수 없다.

  • 하나의 DBMS에 XLog Sender와 Replication Sender를 합쳐서 최대 32 개까지 만들 수 있다.

  • Log Analysis API의 프로토콜 버전과 Replication의 프로토콜 버전이 일치해야 한다.
    XLog Collector가 하나의 Process 내에서 여러 개일 경우, 대응하는 모든 DBMS의 Replication 프로토콜 버전들이 Log Analysis API의 프로토콜 버전과 같아야 한다.

그러나, Replication과는 달리,

  • Foreign Key 컬럼을 가지고 있는 테이블도 로그분석 대상이 될 수 있다.
  • Lazy Mode만 지원한다.

Replication에 대한 자세한 내용은 Replication Manual을 참고한다.

Log Analysis API 사용 방법#

사용자의 애플리케이션에 포함되는 Log Analysis API를 사용하는 방법을 설명한다.

XLog Sender의 사용 방법은 'XLog Sender'를 참고한다.

필요한 파일#

종류

파일명

설명

Header

alaAPI.h

Log Analysis API를 사용해서 클라이언트 프로그램 작성시 include해야 하는 파일이며, alaTypes.h를 include한다.

alaTypes.h

Log Analysis API 사용해서 클라이언트 프로그램 작성시 필요한 Data Type과 매크로를 정의

Library

libala_sl.x

Log Analysis API의 Shared Library

libala.x

Log Analysis API의 Static Library

[표 1‑1] Log Analysis API시 필요한 파일

소스 작성 및 컴파일을 할 때 다음과 같은 사항을 주의해야 한다.

  • 사용자 소스 파일에 'alaAPI.h' 파일을 include해야 한다.

  • 링크 시, Shared Library 또는 Static Library를 링크해야 한다.

  • Library의 확장자는 플랫폼마다 다르다.

데이터 타입#

Log Analysis API에서 사용하는 기본적인 데이터 타입은 아래와 같다.

종류

데이터 타입

설명

Boolean

ALA_BOOL

ALA_TRUE: 참

ALA_FALSE: 거짓

Return Code

ALA_RC

ALA_SUCCESS: 성공

ALA_FAILURE: 실패

Character

Char (SChar)

Signed Character (8 bits)

unsigned char (UChar)

Unsigned Character (8 bits)

Integer

Short (SShort)

Signed Small Integer (16 bits)

unsigned short (UShort)

Unsigned Small Integer (16 bits)

Int (SInt)

Signed Integer (32 bits)

unsigned Int (UInt)

Unsigned Integer (32 bits)

Long (SLong)

Signed Big Integer (64 bits)

unsigned long (ULong)

Unsigned Big Integer (64 bits)

[표 1‑2] Log Analysis API의 기본 데이터 타입

Error Handling#

모든 Log Analysis API는 오류 관리자(Error Manager)를 인자로 받는다. Log Analysis API 호출 결과가 ALA_FAILURE인 경우, 오류 발생 원인을 확인해서 조치해야 한다. 사용자에게 제공하는 오류 정보는 Error Code, Error Level, Error Message이다.

오류 관리자 구조체는 다음과 같다.

typedef struct ALA_ErrorMgr
{
    UInt    mErrorCode;     /* CODE  */
    SChar  mErrorState[6];   /* STATE */
    SChar  mErrorMessage[ALA_MAX_ERROR_MSG_LEN+256];
} ALA_ErrorMgr;

오류 관리자를 사용할 때의 주의사항은 아래와 같다.

  • Log Analysis API를 호출하는 주체(Process 또는 Thread)가 오류 관리자를 생성하고 보관해야 한다.

  • 오류 관리자는 마지막으로 발생한 오류의 정보만 유지한다.

  • Log Analysis API 중 Error Handling 관련 함수의 오류 관리자 인자로 NULL을 사용할 수 없다.

  • Error Handling 관련 함수 이외의 Log Analysis API에서 오류 관리자로 NULL을 사용하면, 오류가 발생 시 Log Manager를 통해 기록되지 않는다.

  • 오류 관리자 구조체의 mErrorCode요소는 내부 정보를 포함하기 있기 때문에, 에러 코드는 반드시 ALA_GetErrorCode()로 얻어야 한다.

ALA_ErrorLevel는 ALA_GetErrorLevel()로 얻을 수 있으며, 오류 수준을 나타낸다.

typedef enum
{
    ALA_ERROR_FATAL = 0,    /* Need to Destroy */
    ALA_ERROR_ABORT,        /* Need to Handshake */
    ALA_ERROR_INFO          /* Information */
} ALA_ErrorLevel;

각 오류 수준에 대한 조치 방법은 아래와 같다.

  • ALA_ERROR_FATAL은 치명적인 오류이므로, ALA_DestroyXLogCollector()를 호출하여 해당 XLog Collector를 종료해야 한다.

  • ALA_ERROR_ABORT는 XLog Collector가 비정상적인 상태임을 나타내므로, ALA_Handshake()를 호출하여 해당 XLog Collector의 Handshake를 다시 수행해야 한다.

  • ALA_ERROR_INFO는 Log Analysis API 호출이 실패했음을 나타낸다. Error Code에 따라 적절한 조치를 해야 한다.

이미 발생한 오류는 Log Manager에 의해 기록된 로그 파일들을 통해 확인할 수 있다. Log Manager에 대한 상세한 사용법은 ALA_EnableLogging()와 ALA_DisableLogging()의 설명을 참고한다.

기본 사용법#

아래의 다이어그램은 Log Analysis API를 사용할 때의 순서를 도식화한 것이다.

basic_use_kor

Log Analysis API를 사용 시, 아래의 사항을 주의해야 한다.

  • XLog Collector 는 STEP 3a~3d에서 모니터링 가능하다.

  • Error Handling API는 모든 STEP에서 사용된다.

  • XLog Collector가 여러 개인 경우, 각 XLog Collector에 대해 STEP 2 ~ 4를 수행한다.

  • ALA_SendACK()를 STEP 3 의 순서에서 매번 호출할 필요는 없다. ACK 전송 시점에 대한 자세한 설명은 ALA_CreateXLogCollector()와 ALA_SendACK()를 참고한다.

  • STEP 3c에서 XLog를 ODBC를 사용해서 DBMS에 적용한다면, Autocommit 옵션을 꺼야 한다.

  • STEP 3a 후에 XLog Sender를 시작시켜야 한다.

  • STEP 3b에서 ALA_ReceiveXLog()와 ALA_GetXLog()를 서로 다른 Thread에서 호출할 수 있다.

  • ALA_FreeXLog를 사용한 후, 해당 XLog와 관련된 데이터를 더 이상 사용하면 안 된다.

Log Analysis API 요약#

Log Analysis API 환경 관리#

종류Log Analysis API설명
Log Analysis API 환경 생성 및 제거 ALA_InitializeAPILog Analysis API를 호출할 수 있는 환경을 생성한다.
ALA_DestroyAPILog Analysis API를 호출할 수 있는 환경을 제거한다.
LoggingALA_EnableLoggingProblem Tracking을 위해 Logging을 활성화한다.
ALA_DisableLoggingLogging을 비활성화한다.

​

XLog Collector 관련 API#

종류 Log Analysis API 설명

XLog Collector 생성 및 준비

ALA_CreateXLogCollector

XLog Sender에 대응하는 XLog Collector를 생성한다.

ALA_AddAuthInfo

XLog Sender 인증 정보를 추가한다.

ALA_RemoveAuthInfo

XLog Sender 인증 정보를 제거한다.

ALA_SetHandshakeTimeout

Handshake의 Timeout을 지정한다.

ALA_SetReceiveXLogTimeout

XLog 수신 Timeout을 지정한다.

Meta 정보와 XLog 수신

ALA_Handshake

XLog Sender의 접속을 대기하고, Handshake를 수행한다.

ALA_ReceiveXLog

XLog를 수신하여 XLog Queue에 XLog를 추가한다.

ALA_GetXLog

XLog Queue에서 XLog를 얻는다.

ALA_SendACK

ACK를 XLog Sender에게 전송한다.

ALA_FreeXLog

XLog를 XLog Pool에 반환한다.

XLog Collector 제거

ALA_DestroyXLogCollector

XLog Collector를 제거한다.

XLog Collector Monitoring

ALA_GetXLogCollectorStatus

XLog Collector의 상태를 얻는다.

XLog Analysis & Conversion API#

종류 Log Analysis API 설명

XLog

ALA_GetXLogHeader

XLog에서 Header 정보를 얻는다.

ALA_GetXLogPrimaryKey

XLog에서 Primary Key 컬럼에 해당하는 데이터를 얻는다.

ALA_GetXLogColumn

XLog에서 Column 데이터 (before and after)를 얻는다.

ALA_GetXLogSavepoint

XLog에서 Savepoint 정보를 얻는다.

ALA_GetXLogLOB

XLog에서 LOB 데이터를 얻는다.

Meta 정보

ALA_GetProtocolVersion

Log Analysis API의 Protocol Version을 얻는다.

ALA_GetReplicationInfo

Replication 정보를 얻는다.

ALA_GetTableInfo

Table OID로 Table 정보를 검색한다.

ALA_GetTableInfoByName

Table 이름과 테이블 소유자 이름으로 Table 정보를 검색한다.

ALA_GetColumnInfo

Column ID로 Table에서 Column 정보를 검색한다.

ALA_GetIndexInfo

Index ID로 Table에서 Index 정보를 검색한다.

ALA_IsHiddenColumn

Column ID로 검색한 컬럼이 숨겨진 것인지 여부를 알아낸다.

Altibase Internal Data Type

ALA_GetInternalNumericInfo

FLOAT, NUMERIC 데이터의 부호와 지수를 얻는다.

ALA_GetAltibaseText

Altibase 내부 데이터를 문자열로 변환한다.

ALA_GetAltibaseSQL

Transaction 관련 XLog를 Altibase SQL 문자열로 변환한다.

ODBC C Conversion

ALA_GetODBCCValue

Altibase 내부 데이터를 ODBC C 의 데이터 타입으로 변환한다.

Error Handling API#

종류 Log Analysis API설명

Error Handling

ALA_ClearErrorMgr

오류 관리자를 초기화한다.

ALA_GetErrorCode

Error Code를 얻는다.

ALA_GetErrorLevel

Error Level을 얻는다.

ALA_GetErrorMessage

구체적인 Error Message를 얻는다.