Skip to content
PDF Oxide

로깅 및 디버그 출력

PDF Oxide는 Rust log 크레이트를 통해 내부 debug, trace, warn, error 로그를 출력합니다. v0.3.24부터 모든 바인딩에 전역 set_log_level / get_log_level 함수가 추가되어 Python, Node.js, Go, C#, Rust에서 일관되게 메시지를 제어할 수 있습니다.

v0.3.21부터 Python 로깅 통합이 완전히 지원됩니다. 메시지가 더 이상 eprintln!을 통해 logging.basicConfig를 우회하지 않습니다.

로그 레벨

레벨 값 설명
OFF 0 모든 로그 출력 비활성화
ERROR 1 추출을 중단시키는 패닉 및 파싱 실패
WARN 2 복구된 오류, 우회 처리된 잘못된 콘텐츠
INFO 3 고수준 작업 (열기, 저장, 인증)
DEBUG 4 내부 결정 (열 감지, 읽기 순서)
TRACE 5 객체 단위 연산자 파싱, 글리프 단위 폰트 메트릭

기본값: WARN.

Python

PDF Oxide의 로그 매크로는 logging.getLogger("pdf_oxide")로 전달됩니다:

Python

import logging
import pdf_oxide

logging.basicConfig(level=logging.DEBUG)
# Equivalent to:
pdf_oxide.set_log_level("debug")

doc = pdf_oxide.PdfDocument("tricky.pdf")
doc.extract_text(0)  # emits debug logs to root handler

C++

#include <pdf_oxide/pdf_oxide.hpp>

pdf_oxide::set_log_level(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Swift

import PdfOxide

setLogLevel(4)   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

R

library(pdfoxide)

pdf_set_log_level(4L)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Julia

using PdfOxide

set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Zig

const pdf_oxide = @import("pdf_oxide");

pdf_oxide.setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Objective-C

#import <POXPdfOxide.h>

[POXSigning setLogLevel:4];   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Elixir

PdfOxide.set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

PDF Oxide 출력만 별도 로거로 라우팅하기:

Python

import logging

handler = logging.FileHandler("pdf_oxide.log")
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))

log = logging.getLogger("pdf_oxide")
log.addHandler(handler)
log.setLevel(logging.DEBUG)

Node.js

Node.js

const { setLogLevel } = require("pdf-oxide");

setLogLevel("debug");          // one of "off"|"error"|"warn"|"info"|"debug"|"trace"

C++

#include <pdf_oxide/pdf_oxide.hpp>

pdf_oxide::set_log_level(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Swift

import PdfOxide

setLogLevel(4)   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

R

library(pdfoxide)

pdf_set_log_level(4L)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Julia

using PdfOxide

set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Zig

const pdf_oxide = @import("pdf_oxide");

pdf_oxide.setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Objective-C

#import <POXPdfOxide.h>

[POXSigning setLogLevel:4];   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Elixir

PdfOxide.set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

로그는 [LEVEL] message 형식으로 stderr에 출력됩니다. 원하는 로거로 파이프할 수 있습니다:

Node.js

const { pipeline } = require("stream");

pipeline(
  process.stderr,
  myBunyanSink,
  (err) => err && console.error("log pipe failed", err)
);

Go

Go

import pdfoxide "github.com/yfedoseev/pdf_oxide/go"

pdfoxide.SetLogLevel(pdfoxide.LogDebug)

C++

#include <pdf_oxide/pdf_oxide.hpp>

pdf_oxide::set_log_level(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Swift

import PdfOxide

setLogLevel(4)   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

R

library(pdfoxide)

pdf_set_log_level(4L)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Julia

using PdfOxide

set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Zig

const pdf_oxide = @import("pdf_oxide");

pdf_oxide.setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Objective-C

#import <POXPdfOxide.h>

[POXSigning setLogLevel:4];   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Elixir

PdfOxide.set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

출력을 캡처하려면 바이너리 시작 전에 RUST_LOG 환경 변수를 설정하세요:

RUST_LOG=pdf_oxide=debug ./my-app

C#

C#

using PdfOxide.Core;

PdfOxide.Logging.SetLogLevel(LogLevel.Debug);

C++

#include <pdf_oxide/pdf_oxide.hpp>

pdf_oxide::set_log_level(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Swift

import PdfOxide

setLogLevel(4)   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

R

library(pdfoxide)

pdf_set_log_level(4L)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Julia

using PdfOxide

set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Zig

const pdf_oxide = @import("pdf_oxide");

pdf_oxide.setLogLevel(4);   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Objective-C

#import <POXPdfOxide.h>

[POXSigning setLogLevel:4];   // 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

Elixir

PdfOxide.set_log_level(4)   # 0=Off 1=Error 2=Warn 3=Info 4=Debug 5=Trace

ILogger에 연결하기:

C#

var logger = loggerFactory.CreateLogger("PdfOxide");
PdfOxide.Logging.OnLog += (level, message) =>
{
    logger.Log(Map(level), message);
};

Rust

log 호환 백엔드(env_logger, tracing-log, slog-stdlog 등)를 자유롭게 사용할 수 있습니다. PDF Oxide는 pdf_oxide 타겟을 통해 로그를 출력합니다:

Rust

fn main() {
    env_logger::builder()
        .filter_module("pdf_oxide", log::LevelFilter::Debug)
        .init();

    let doc = pdf_oxide::PdfDocument::open("tricky.pdf").unwrap();
    let _ = doc.extract_text(0);
}

DEBUG는 무엇을 보여주나요?

알아두면 유용한 대표적인 디버그 메시지:

  • Detected document script: Latin / Arabic / CJK — 읽기 순서 휴리스틱 선택 결과.
  • is_single_column_region = true — 열 감지기가 단일 열 레이아웃으로 폴백.
  • Falling back to system font DejaVu Sans for ArialMT — 폰트 해석 실패.
  • Authenticating with user password — authenticate() 성공 후 출력.
  • Table detector: rejected 3 edges via coverage filter — 엣지 필터링 적용.

TRACE는 무엇을 보여주나요?

TRACE는 객체별 콘텐츠 스트림 파싱과 글리프별 폰트 메트릭 해석을 포함합니다. 특정 페이지가 잘못 추출될 때 어떤 연산자가 무엇을 생성했는지 파악하는 데 유용합니다. 페이지당 수천 줄이 출력될 수 있습니다.

관련 문서