spakky-logging

Spakky Framework를 위한 구조화 로깅 시스템입니다. Context-local log binding, formatter 설정, AOP 기반 메서드 호출 로깅, PostProcessor 기반 자동 설정을 제공합니다.

설치

pip install spakky-logging

빠른 시작

1. 플러그인 자동 등록

spakky-logging은 load_plugins()를 통해 자동으로 로드됩니다.

app = SpakkyApplication(ApplicationContext()).load_plugins().scan(my_app).start()

2. `@logged`로 메서드 표시

from spakky.plugins.logging import logged

class UserService:
    @logged()
    async def create_user(self, name: str, password: str) -> User:
        ...

3. 설정(선택)

LoggingConfig로 기본값을 override합니다.

LoggingConfig는 @Configuration Pod로 로드되며, pydantic-settings를 통해 SPAKKY_LOGGING__* 환경변수를 읽습니다.

export SPAKKY_LOGGING__LEVEL=10
export SPAKKY_LOGGING__FORMAT=json
export SPAKKY_LOGGING__MASK_KEYS='["password", "token", "secret"]'
export SPAKKY_LOGGING__SLOW_THRESHOLD_MS=500

4. LogContext 전파

모든 log record에 자동 포함될 contextual key-value pair를 바인딩합니다.

from spakky.plugins.logging import LogContext

LogContext.bind(request_id="req-123", user_id="u-456")

with LogContext.scope(trace_id="t-789"):
    # 이 block 안의 모든 log는 trace_id를 포함
    ...

주요 기능

기능	설명
`@logged()` annotation	AOP 기반 method call/result/error 자동 logging
`LogContext`	contextvars 기반 structured context 전파
`ContextInjectingFilter`	모든 `LogRecord`에 LogContext value 주입
`SpakkyTextFormatter`	pipe로 구분된 text format
`SpakkyJsonFormatter`	line당 JSON object 하나
`SpakkyPrettyFormatter`	개발용 ANSI color multi-column format
`LoggingConfig`	중앙 logging configuration용 `@Configuration` pod
`LoggingSetupPostProcessor`	application start 시 root logger 자동 설정
민감 데이터 masking	log output에서 `password`, `token`, `secret` 등을 masking
느린 호출 감지	method 실행 시간이 threshold를 넘으면 warning 출력
결과 truncation	긴 return value를 log output에서 잘라냄

개발 검증

패키지 단위 검증은 해당 패키지 디렉토리에서 실행합니다.

uv run ruff format .
uv run ruff check .
uv run pyrefly check
uv run pytest

pytest는 각 패키지 pyproject.toml의 coverage 설정을 사용합니다.

라이선스

MIT License

Metadata

Release files for spakky-logging 8.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spakky-logging 8.1.0
File	Size	Uploaded
spakky_logging-8.1.0.tar.gz	10.7 kB	Aug 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spakky-logging 8.1.0
File	Interpreter	ABI	Platform	Reset
spakky_logging-8.1.0-py3-none-any.whl 16.0 kB Aug 22, 2026	Python 3	none	any	Details

Total release size: 26.7 kB

Release files / spakky_logging-8.1.0.tar.gz

Download URL	spakky_logging-8.1.0.tar.gz
Size	10.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`0fef22da39013e39469cd937741b18f112223a390ec1677805a47fe6b6588543`
BLAKE2b-256 checksum How to use checksums	`14009040281efc7639214e4e492e2215e7088cf84004f11d5daf0972a23cade3`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/E5presso/spakky-framework
Publishing commit: github.com/E5presso/spakky-framework/tree/e29216bdd41ad11f48d1f6147368d4b748fefadc

Workflow

Publishing configuration: github.com/E5presso/spakky-framework/blob/e29216bdd41ad11f48d1f6147368d4b748fefadc/.github/workflows/release.yml
Publishing logs: github.com/E5presso/spakky-framework/actions/runs/32573122611/attempts/1

Artifact

Subject: spakky_logging-8.1.0.tar.gz
SHA-256 checksum: 0fef22da39013e39469cd937741b18f112223a390ec1677805a47fe6b6588543 Verifying attestations

Release files / spakky_logging-8.1.0-py3-none-any.whl

Download URL	spakky_logging-8.1.0-py3-none-any.whl
Size	16.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`23bae4d84dcbdc50542cf63c9938980d9d64af3c7ee2d4797d3f5ffb46c7b9f5`
BLAKE2b-256 checksum How to use checksums	`cf3c0ec12a249af14ec78a3715336a99f8d6be455104c2793be28f512fb59c07`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/E5presso/spakky-framework
Publishing commit: github.com/E5presso/spakky-framework/tree/e29216bdd41ad11f48d1f6147368d4b748fefadc

Workflow

Publishing configuration: github.com/E5presso/spakky-framework/blob/e29216bdd41ad11f48d1f6147368d4b748fefadc/.github/workflows/release.yml
Publishing logs: github.com/E5presso/spakky-framework/actions/runs/32573122611/attempts/1

Artifact

Subject: spakky_logging-8.1.0-py3-none-any.whl
SHA-256 checksum: 23bae4d84dcbdc50542cf63c9938980d9d64af3c7ee2d4797d3f5ffb46c7b9f5 Verifying attestations