콘텐츠로 이동

데이터 전송


장기 보관이 필요하지만 업데이트 빈도가 낮은 데이터(예: 로그)는 데이터 전송 기능을 통해 오브젝트 스토리지에 자동으로 저장하거나 Kafka 등 외부 시스템으로 실시간 전송할 수 있습니다. 이 기능은 규칙에 따라 사용자가 필요한 데이터를 필터링하여 저비용 장기 아카이빙을 구현하며, 이후 2차 가공 처리를 지원합니다.

규칙이 적용된 후 데이터 전송 페이지에서 조회 기간과 규칙을 설정하면 재조회를 지원하는 대상에서 처리 완료된 데이터를 검색할 수 있습니다. 조회 가능한 시간은 대상의 데이터 처리 주기에 따라 달라집니다.

데이터 전송은 메트릭 데이터 소스도 지원합니다. 규칙을 생성하거나 편집할 때 메트릭을 선택하고 필터 조건을 구성하여 규칙에 부합하는 메트릭 데이터를 외부 서비스로 전송할 수 있습니다. 구체적인 작업은 전송 규칙 정의를 참고하세요.

로컬 또는 자체 클라우드 환경에 데이터를 보관해야 하는 경우 LogBamboo를 대상으로 선택하고 콘솔을 통해 과거 기록을 조회할 수 있습니다.

기능 원리

LogBamboo를 사용하는 경우 LogBamboo로 데이터 전송을 참고하세요.

JSON 형식으로 오브젝트 스토리지에 전송하는 경우를 예로 들면, 작동 흐름은 다음과 같습니다. 규칙에 부합하는 사용자 보고 데이터는 먼저 서버 로컬 디스크의 임시 파일에 한 줄씩 기록됩니다. 해당 임시 파일의 크기가 미리 설정된 값(예: 256MB)에 도달하거나 지속 쓰기 시간이 설정된 시간(예: 1시간)을 초과하면 시스템이 현재 파일을 자동으로 닫고 새 임시 파일을 생성하여 계속 데이터를 수신합니다.

동시에 백그라운드 서비스가 닫힌 임시 파일을 지속적으로 스캔하여 gzip 형식으로 압축해 크기를 줄인 후, 미리 정의된 경로 규칙에 따라 지정한 오브젝트 스토리지 위치에 업로드합니다. 저장된 데이터를 검색해야 할 때 시스템은 동일한 경로 규칙에 따라 오브젝트 스토리지에서 관련 파일을 찾고, 다운로드 및 압축 해제한 뒤 입력한 검색 조건과 한 줄씩 일치시킵니다.

파일 형식 설명

JSON 저장 형식을 선택하면 일반 아카이브는 gzip으로 압축됩니다. 압축을 해제하면 파일 내용이 여러 줄의 텍스트로 표시되며, 각 줄은 하나의 원본 데이터 레코드에 해당하고 데이터는 JSON 형식으로 완전하게 저장됩니다. 파일의 빈 줄은 시스템에서 자동으로 무시됩니다.

Parquet 저장 형식을 선택하면 파일은 Parquet 내부 GZIP으로 압축되며 일반 gzip 파일처럼 압축 해제할 수 없습니다. 오브젝트 스토리지 규칙에서 암호화 저장이 활성화된 경우 다운로드한 아카이브는 먼저 복호화해야 합니다.

일반적인 로그 유형 데이터 전송 파일은 다음과 같습니다.

여기서 date는 필수 필드로 해당 데이터의 시간을 나타내며 밀리초 단위 Unix 타임스탬프이고, message 필드는 구체적인 로그 내용입니다.

{"__docid":"L_1750649205520_d1cciupkac7k1683bhq0","__namespace":"backup_log","date":1750649205520,"date_ns":168000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/gin.log","host":"X.local","log_read_lines":2,"message":"[GIN] 2025/06/23 - 11:26:43 | 200 | 1.012923708s |       127.0.0.1 | GET     \"/metrics\"","message_length":87,"service":"default","source":"default","status":"unknown"}

{"__docid":"L_1750649205516_d1cciupkac7k1683bhqg","__namespace":"backup_log","date":1750649205516,"date_ns":897000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/gin.log","host":"X.local","log_read_lines":1,"message":"[GIN] 2025/06/23 - 11:26:38 | 200 | 1.012696542s |       127.0.0.1 | GET     \"/metrics\"","message_length":87,"service":"default","source":"default","status":"unknown"}

{"__docid":"L_1750649206520_d1cciupkac7k1683bhr0","__namespace":"backup_log","date":1750649206520,"date_ns":948000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":150,"message":"2025-06-23T11:26:46.520+0800\tWARN\thost_processes\tprocess/input.go:332\tprocess: {\"pid\":411}, proc.PageFaults(): not implemented yet","message_length":130,"service":"default","source":"default","status":"unknown"}

{"__docid":"L_1750649205520_d1cciupkac7k1683bhrg","__namespace":"backup_log","date":1750649205520,"date_ns":419000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":9,"message":"2025-06-23T11:26:43.876+0800\tWARN\tcontainer\tcontainer/impl.go:254\tendpoint unix:///var/run/crio/crio.sock does not exist, maybe it is not running, skip","message_length":151,"service":"default","source":"default","status":"unknown"}

{"__docid":"L_1750649205517_d1cciupkac7k1683bhs0","__namespace":"backup_log","date":1750649205517,"date_ns":79000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":1,"message":"2025-06-23T11:26:38.365+0800\tWARN\thttp\thttpapi/http.go:494\tlistener.Close failed: close tcp [::]:9529: use of closed network connection","message_length":135,"service":"default","source":"default","status":"unknown"}
{"__docid":"L_1750649205517_d1cciupkac7k1683bhsg","__namespace":"backup_log","date":1750649205517,"date_ns":80000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":2,"message":"2025-06-23T11:26:38.365+0800\tWARN\thttp\thttpapi/http.go:494\tlistener.Close failed: close tcp [::]:9529: use of closed network connection","message_length":135,"service":"default","source":"default","status":"unknown"}

파일 이름 지정 및 저장 경로

[{$path_prefix}/]{$workspace_uuid}/[{$data_type}/]

{$rule_name}/{$year}/{$month}/{$day}/{$hour}/{$time}-{$hostname}.gz

[]로 묶인 부분은 "선택 항목"을 나타내며, 구체적인 내용은 아래 설명을 참고하세요.

변수
설명
예시 비고
$path_prefix 경로 접두사 path/to/backup 선택 사항이며, 백업 규칙 생성 시의 저장 경로 옵션에 해당합니다
오브젝트 스토리지는 /로 시작하는 key를 지원하지 않으므로 /로 시작하지 마세요
$workspace_uuid 워크스페이스 ID wksp_d9a1851859e040469d290409bc17cceb
$data_type 백업 데이터 유형, 선택 가능한 값:

  • logging: 로그
  • rum: 실제 사용자 모니터링(RUM)
  • tracing: 트레이스
  • event: 이벤트
  • audit_event: 감사 이벤트
  • tracing 로그는 기본 데이터 유형이므로 로그 유형 데이터의 경우 {$data_type}/(즉 logging/) 부분을 생략해야 합니다
    $rule_name 규칙 이름 backup_logging_for_test 규칙 생성 시의 규칙 이름 옵션에 해당합니다
    영문 사용을 권장합니다
    $year 로그 발생 시간의 연도, 4자리 2025 UTC 시간대
    $month 로그 발생 시간의 월, 2자리 03 UTC 시간대
    $day 로그 발생 시간의 일, 2자리 01 UTC 시간대
    $hour 로그 발생 시간의 시, 2자리 22 UTC 시간대
    $time 파일에서 마지막 로그의 발생 시간
    형식: HHMMSS + 3자리 밀리초
    220607889 UTC 시간대
    $hostname 호스트 이름을 MD5로 계산한 후 앞 16자리 c6a92aafa992599c 파일을 직접 구성할 때 현재 파일의 crc64를 사용하거나
    64비트 난수를 무작위로 생성한 후 16진수로 변환할 수 있습니다

    경로 예시:

    wksp_d9a1851859e040469d290409bc17cceb/backup_logging_for_test/2025/05/06/17/175950000-c6a92aafa992599c.gz

    path/to/backup/wksp_d9a1851859e040469d290409bc17cceb/tracing/test-minio/2025/05/06/17/175950000-c6a92aafa992599c.gz

    파일 분할 규칙
    • 시간 경계: 단일 파일에는 동일한 1시간 이내의 로그만 포함되며, 절대 시간 경계를 넘지 않습니다
    • 크기 경계: 비압축 원본 파일은 256 MB~512 MB 사이로 유지하며, gzip 압축 후에는 일반적으로 수십 MB~100여 MB입니다. 너무 크거나 작으면 검색 효율이 떨어집니다

    외부 파일을 데이터 전송 규칙에서 생성되는 형식과 경로 규칙에 맞춰 오브젝트 스토리지에 업로드하면 콘솔에서도 동일한 방식으로 검색하고 표시합니다.

    시작하기

    전송 규칙 생성

    전송 대상 유형에 따라 비즈니스 요구에 맞는 데이터 전송 규칙을 생성합니다.

    유형 전송 대상
    내장 스토리지 Guance
    오브젝트 스토리지 AWS S3, Huawei Cloud OBS, Alibaba Cloud OSS, Volcengine TOS, Google Cloud GCS
    분석 플랫폼 Apache Doris, TiDB Cloud Lake, LogBamboo
    메시지 큐 Kafka

    전송 규칙 관리

    데이터 전송 규칙 목록에서 일련의 작업을 통해 관리할 수 있습니다.

    데이터 조회 권한

    데이터 전송 규칙을 생성할 때 워크스페이스의 모든 멤버가 데이터를 조회하도록 허용하거나, 데이터를 조회할 수 있는 멤버 역할을 지정할 수 있습니다. 구체적인 설정은 데이터 조회 권한 정의를 참고하세요.

    파일 복호화

    AWS S3, Huawei Cloud OBS, Alibaba Cloud OSS, Volcengine TOS, Google Cloud GCS로 전송되며 저장 형식이 JSON 또는 Parquet이고 암호화 저장이 활성화된 아카이브 파일에 적용됩니다. AWS S3의 Apache Iceberg 형식에는 적용되지 않습니다.

    파일 확장자 처리 방식 출력 파일
    .lock.gz 복호화 도구로 복호화하고 gzip 압축 해제 JSON 라인 파일, 예: .jsonl
    .parquet.lock.gz 복호화 도구로 복호화하며 gzip 압축 해제는 수행하지 않음 .parquet
    .gz 암호화되지 않음, gzip 압축 해제 직접 수행 JSON 라인 파일, 예: .jsonl
    .parquet.gz 암호화되지 않음, Parquet 읽기 도구로 직접 열기 Parquet 파일

    준비 작업

    1. 오브젝트 스토리지에서 전체 아카이브 파일을 다운로드하고 원본 사본을 보관합니다.
    2. 워크스페이스 ID(UUID)를 가져옵니다. 파일이 속한 워크스페이스의 관리 > 워크스페이스 설정 > 기본 정보에서 복사할 수 있으며, wksp_로 시작하는 전체 값을 사용합니다.
    3. 사용 가능한 Go 환경을 준비하고 복호화 도구 decrypt.go 다운로드를 수행합니다. 도구는 Go 표준 라이브러리에만 의존하며 로컬에서 파일을 처리하므로 오브젝트 스토리지 액세스 키가 필요하지 않습니다.

    작업 단계

    다음 명령은 macOS 또는 Linux의 Bash, Zsh에 적용됩니다. 도구와 아카이브를 같은 디렉터리에 두고 해당 디렉터리에서 터미널을 엽니다. 실제 파일 이름에 맞게 -in과 -out을 수정하고 -workspace 값을 준비 작업에서 복사한 전체 워크스페이스 ID로 바꿉니다. -out에는 아직 존재하지 않는 출력 경로를 사용해야 합니다.

    1. Go 환경 확인

    go version
    

    2. 기본 복호화 파라미터 사용

    도구에는 기본 IV(초기화 벡터, 즉 암호화 시 사용하는 파라미터)가 내장되어 있습니다. 아카이브가 기본 암호화 설정을 사용하는 경우 별도로 IV를 가져오거나 입력할 필요가 없습니다. 다음 명령을 실행하여 도구가 내장 기본값을 사용하도록 합니다.

    unset KODO_BACKUP_IV
    
    배포 환경에서 사용자 정의 암호화 파라미터를 사용하는 경우

    서버에서 backup_log.iv를 수정한 적이 있다면 해당 배포 환경 유지 관리를 담당하는 사람에게 문의하여 파일 생성 시 사용한 설정 값을 가져오세요. 그런 다음 아래 명령으로 위의 unset 명령을 대체하세요.

    export KODO_BACKUP_IV='文件生成时使用的 IV'
    

    KODO_BACKUP_IV는 로컬 복호화 도구에 해당 값을 전달할 뿐입니다. 기본값을 사용한다는 의미로 빈 문자열을 설정하지 마세요. 구성이 변경된 적이 있다면 기존 파일에는 생성 당시의 값을 계속 사용해야 합니다.

    3. 복호화 실행

    go run decrypt.go \
      -in "./archive.lock.gz" \
      -out "./archive.jsonl" \
      -workspace "wksp_your_workspace_uuid"
    

    도구가 복호화와 gzip 압축 해제를 자동으로 수행하며, 생성된 .jsonl은 JSON을 한 줄씩 읽을 수 있으므로 다시 압축 해제할 필요가 없습니다.

    go run decrypt.go \
      -in "./archive.parquet.lock.gz" \
      -out "./archive.parquet" \
      -workspace "wksp_your_workspace_uuid"
    

    도구가 복호화한 후 Parquet 파일을 생성하며, Parquet 읽기 도구로 직접 스키마와 데이터를 확인합니다. 복호화 도구는 전체 Parquet 구조 검증을 수행하지 않습니다.

    도구는 복호화된 파일 헤더를 기준으로 형식을 식별하며 파일 이름에 의존하지 않습니다. 입력 파일은 원본 그대로 유지됩니다. 출력 경로가 이미 존재하면 덮어쓰지 않으며, 처리에 실패하면 이번에 생성된 불완전한 출력 파일을 삭제하려고 시도합니다.

    4. 복호화 결과 확인

    명령이 성공적으로 종료되면 터미널에 파일 형식에 따라 해당 안내가 출력됩니다.

    Restored decompressed JSON/NDJSON: ./archive.jsonl
    

    또는:

    Restored Parquet: ./archive.parquet
    
    • JSON 라인 파일: 각 줄이 JSON으로 파싱되는지 확인하고 시간, 데이터 내용 등 필드를 표본 검사합니다.
    • Parquet 파일: Parquet 읽기 도구로 열어 스키마와 데이터 내용을 확인하고, gunzip을 다시 실행하지 마세요.

    선택 사항: 컴파일 후 사용

    go build -o backup-decrypt decrypt.go
    ./backup-decrypt -in "./archive.lock.gz" -out "./archive.jsonl" -workspace "wksp_your_workspace_uuid"
    

    컴파일된 도구는 여전히 KODO_BACKUP_IV를 통해 사용자 정의 IV를 읽습니다. 동일한 운영 체제와 아키텍처의 머신에 복사하여 실행할 수 있으며, 대상 머신에는 Go를 설치할 필요가 없습니다.

    암호화되지 않은 파일

    일반 .gz 파일은 직접 압축 해제할 수 있습니다. 출력 파일 이름은 아직 존재하지 않는 경로로 선택해야 합니다.

    (set -C; gzip -dc "./archive.gz" > "./archive.jsonl")
    

    이 명령은 원본 아카이브를 보존합니다. 출력 파일이 이미 존재하면 오류가 발생하고 중단되므로 파일 이름을 변경하세요. .parquet.gz는 Parquet 내부 GZIP 압축을 사용하므로 Parquet 읽기 도구에 직접 전달하며 이 명령을 사용하지 않습니다.

    자주 묻는 질문

    증상 확인 및 처리
    unrecognized decrypted header wksp_로 시작하는 전체 워크스페이스 ID, 파일 생성 시의 IV, 파일 무결성을 확인하세요. 암호화되지 않은 파일은 복호화 도구로 처리해서는 안 됩니다.
    invalid gzip header 또는 gzip 검증 실패 복호화 파라미터를 확인하고 원본 아카이브를 다시 다운로드하여 손상 또는 잘림 여부를 배제하세요.
    Parquet에 gunzip 실행 시 오류 발생 Parquet 읽기 도구로 복호화된 파일을 직접 여세요.
    file exists 아직 존재하지 않는 출력 파일 이름으로 변경하세요.
    go: command not found Go를 설치하거나 다른 머신에서 컴파일한 후 호환되는 실행 파일을 복사하세요.
    permission denied 입력 파일을 읽을 수 있고 출력 디렉터리에 쓸 수 있는지 확인하세요.
    no space left on device 압축 해제 후의 데이터 양에 맞게 디스크 공간을 확보하세요.
    no such file or directory 도구와 아카이브 경로를 확인하고 출력 디렉터리를 미리 생성하세요.

    문서 평가

    이 페이지가 도움이 되었나요?