시스템 개발 및 관리/Dagster 사용법

Dagster 똑똑하게 실행하기: -m과 -f 옵션, 언제 어떻게 사용할까?

Data Jun 2025. 5. 8. 09:42

안녕하세요, Dagster 사용자 여러분! 데이터 파이프라인을 구축하고 관리하는 데 있어 Dagster는 정말 강력한 도구입니다. 하지만 처음 Dagster를 접하거나, 프로젝트 구조를 잡아갈 때 코드를 로드하는 방식, 특히 dagster dev 명령어의 -m 옵션과 -f 옵션 사이에서 어떤 것을 선택해야 할지 고민될 때가 있습니다. 오늘은 이 두 가지 옵션의 차이점을 명확히 알아보고, 특히 여러분의 프로젝트가 파이썬 패키지 형태로 구성되어 있을 때 왜 dagster dev -m src.definitions와 같은 방식이 효과적으로 동작하는지 그 원리를 함께 파헤쳐 보겠습니다!

 

Dagster는 어떻게 우리 코드를 이해할까요?

Dagster가 우리의 자산(Assets), 작업(Jobs), 스케줄(Schedules) 등을 실행하고 관리하려면, 먼저 이 정의들이 어디에 어떻게 작성되어 있는지 알아야 합니다. dagster dev와 같은 CLI 명령어는 바로 이 "코드 로딩" 과정을 수행하며, 이때 사용자가 제공하는 옵션에 따라 로딩 방식이 달라집니다.

 

1. -f <파일 경로> 옵션: 특정 파일을 직접 지정하기

-f 또는 --python-file 옵션은 가장 직관적인 방법 중 하나입니다. Dagster에게 Definitions 객체 (또는 과거 버전의 RepositoryDefinition)가 포함된 단일 파이썬 파일의 경로를 직접 알려줍니다.

예를 들어, 여러분의 Definitions 객체가 SL-PROJECT/src/definitions.py 파일 안에 있다면 다음과 같이 실행할 수 있습니다.

dagster dev -f src/definitions.py

장점:

  • 매우 간단하고 명시적입니다.
  • 단일 파일로 구성된 작은 프로젝트나 빠른 테스트에 유용합니다.

단점:

  • 패키지 컨텍스트 문제: 해당 파일(src/definitions.py)이 더 큰 패키지(src)의 일부이고, 패키지 내 다른 모듈을 상대 경로(from .assets import ...)로 임포트하는 경우 문제가 발생할 수 있습니다. -f 옵션으로 직접 실행된 파일은 파이썬 인터프리터에 의해 최상위 모듈로 취급되어 패키지 구조를 제대로 인식하지 못할 수 있기 때문입니다.
  • PYTHONPATH 의존성: 실행하는 위치나 PYTHONPATH 설정에 따라 임포트 경로가 달라질 수 있어 일관성이 떨어질 수 있습니다.
  • 확장성: 프로젝트가 커져 여러 파일과 모듈로 나뉘게 되면 관리하기 어려워집니다.

 

2. -m <모듈 경로> 옵션: 파이썬 모듈로 로드하기 (강력 추천!)

 

-m 또는 --module-name 옵션은 Dagster에게 Definitions 객체가 포함된 파이썬 모듈의 경로를 알려줍니다. 여기서 "모듈 경로"란 파이썬의 임포트 시스템이 사용하는 점(.)으로 구분된 경로를 의미합니다.

예를 들어, 이전 사용자 질문에서 제시된 SL-PROJECT/src/definitions.py 구조에서 Definitions 객체를 로드하려면 다음과 같이 실행합니다. (이때, SL-PROJECT 디렉토리에서 명령어를 실행한다고 가정합니다.)

 

장점:

  • 올바른 패키지 컨텍스트: 이 방식은 파이썬의 표준 모듈 로딩 메커니즘을 사용합니다. 따라서 src라는 패키지 안에 있는 definitions 모듈로 정확히 인식되어, src/definitions.py 파일 내에서 사용되는 상대 경로 임포트 (from .assets import ... 등)가 문제없이 동작합니다.
  • 프로젝트 구조화에 유리: 코드를 여러 모듈과 서브 패키지로 구성하는 현대적인 파이썬 프로젝트 구조에 매우 적합합니다.
  • 일관성 및 이식성: PYTHONPATH가 올바르게 설정되어 있거나, 프로젝트 루트에서 실행하는 경우 파이썬이 모듈을 일관되게 찾을 수 있도록 도와줍니다.

 

왜 -m src.definitions는 패키지 내의 definitions.py를 실행할 수 있을까요?

이것이 바로 파이썬의 모듈 시스템과 Dagster의 영리한 연동 덕분입니다!

  1. 파이썬의 모듈 탐색: dagster dev -m src.definitions 명령을 실행하면, Dagster는 파이썬 인터프리터에게 " src 라는 이름의 패키지(또는 모듈)를 찾고, 그 안에서 definitions 라는 이름의 모듈을 찾아줘" 라고 요청합니다.
  2. sys.path와 PYTHONPATH: 파이썬은 sys.path에 등록된 여러 경로에서 src를 찾기 시작합니다. sys.path에는 다음이 포함될 수 있습니다.
    • 명령어를 실행하는 현재 작업 디렉토리 (일반적으로 프로젝트 루트인 SL-PROJECT)
    • 환경 변수 PYTHONPATH에 지정된 디렉토리들
    • 파이썬 설치 시 기본 라이브러리 경로 등
  3. 패키지 인식: SL-PROJECT 디렉토리에서 명령어를 실행하면, 그 하위의 src 디렉토리(내부에 __init__.py 파일이 존재하므로 패키지로 인식)를 파이썬이 발견할 수 있습니다.
  4. 모듈 로딩: src 패키지를 찾은 후, 파이썬은 그 안에서 definitions라는 이름의 모듈, 즉 definitions.py 파일을 찾아 로드합니다.
  5. Dagster의 Definitions 객체 탐색: src.definitions 모듈이 성공적으로 로드되면, Dagster는 해당 모듈 내에서 Definitions 타입의 객체를 찾습니다. 보통 defs라는 이름의 객체를 우선적으로 찾거나, 해당 모듈에 Definitions 객체가 하나만 있다면 그것을 사용합니다. (만약 특정 이름의 객체를 지정하고 싶다면 -a <객체_이름> 옵션을 추가할 수 있습니다. 예: dagster dev -m src.definitions -a my_custom_defs)

결과적으로 -m 옵션은 단순한 파일 실행이 아니라, 파이썬의 강력한 모듈 및 패키지 시스템을 활용하여 코드를 컨텍스트에 맞게 로드하는 방식입니다.

언제 어떤 옵션을 사용해야 할까요?

  • -f <파일 경로> 옵션:
    • 아주 작은, 단일 파일로 구성된 Dagster 코드를 테스트할 때.
    • 프로젝트가 아직 패키지 구조를 갖추지 않았을 때.
    • 임시적인 스크립트 실행 시.
  • -m <모듈 경로> 옵션:
    • 대부분의 경우, 특히 프로젝트가 여러 파일과 디렉토리(패키지)로 구성된 경우 강력히 권장됩니다.
    • 코드 내에서 상대 경로 임포트를 사용할 때.
    • workspace.yaml 파일에서 python_module 로딩 방식을 사용할 때와 일관성을 유지하고 싶을 때.
    • 더 깔끔하고 유지보수하기 쉬운 프로젝트 구조를 지향할 때.

 

마무리하며

 

Dagster 프로젝트를 진행할 때는 가급적 코드를 파이썬 패키지로 잘 구조화하고, -m 옵션 (CLI) 또는 workspace.yaml의 python_module 설정을 통해 코드를 로드하는 것이 좋습니다. 이는 Python의 장점을 최대한 활용하면서 Dagster 프로젝트의 안정성과 확장성을 높이는 방법입니다.

이제 -m과 -f 옵션의 차이, 그리고 -m src.definitions가 어떻게 마법처럼 동작하는지 조금 더 명확해지셨기를 바랍니다! 즐거운 데이터 파이프라이닝 되세요!