Jira Cloud용 Openflow 커넥터 정보

Jira Cloud용 Openflow 커넥터 정보

이 주제는 Openflow Connector for Jira Cloud의 기본 개념, 워크플로우, 제한 사항을 설명해요. 이 커넥터는 여러 Atlassian Jira Cloud 엔티티의 데이터를 Snowflake로 수집해요. 커넥터는 두 개의 별도 플로우로 구성돼요.

출처: Snowflake 문서

본문

참고: 이 커넥터는 Snowflake Connector Terms가 적용돼요.

이 주제는 Openflow Connector for Jira Cloud의 기본 개념, 워크플로우, 제한 사항을 설명해요. Openflow Connector for Jira Cloud는 여러 Atlassian Jira Cloud 엔티티의 데이터를 Snowflake로 수집해요. 커넥터는 두 개의 별도 플로우로 구성돼요:

  • Core flow — Jira Cloud REST API를 사용해 이슈, 프로젝트, 코멘트, 변경 기록(changelogs), 작업 기록(worklogs), 사용자, 삭제된 이슈, 투표, 워처(watchers), 원격 링크, 이슈 보안 스킴, 그리고 이슈 유형·우선순위·해결 상태·상태에 대한 조회 테이블(lookup tables)을 검색해요.
  • Agile flow — Jira Agile REST API를 사용해 보드, 스프린트, 보드-스프린트 매핑, 보드-프로젝트 매핑, 보드-이슈 매핑을 검색해요.

두 플로우 모두 명시적 컬럼 스키마가 있는 전용 Snowflake 테이블에 데이터를 저장해요. 두 플로우는 서로 다른 이름의 테이블을 만들므로 같은 Snowflake 대상 스키마에 쓸 수 있어요.

다음을 하려면 이 커넥터를 사용해요:

  • 크로스 팀 가시성과 엔지니어링, 지원, 프로젝트 워크플로우에 대한 더 깊은 인사이트를 위해 Jira 데이터를 Snowflake에 중앙화
  • 선택 가능한 선택적 테이블의 부분집합과 함께, 광범위한 Jira 엔티티 집합을 쿼리 준비가 된 별도의 Snowflake 테이블로 수집
  • 프로젝트별 병렬 수집(per-project parallel ingestion)으로 Jira 이슈를 추출해 데이터 로드를 더 빠르게
  • Jira 감사 로그 폴링으로 삭제된 이슈 추적
  • 별도의 agile 플로우로 Jira Agile 데이터를 선택적으로 수집

참고: 이전에 이전 버전의 Jira Cloud 커넥터를 배포했다면 Migrate from the legacy Openflow Connector for Jira Cloud에서 단계별 마이그레이션 가이드를 참고해요.

대상 테이블(Destination tables)

커넥터는 구성된 Snowflake 대상 스키마에 다음 테이블들을 만들어요. 대부분의 테이블은 커넥터가 정의한 고정 컬럼 스키마를 가져요. ISSUE 테이블은 예외로, 그 컬럼은 Issue Fields 구성에 의해 결정되며 Jira 인스턴스의 커스텀 필드를 포함할 수 있어요. 자세한 내용은 Issue fields configuration을 참고해요.

Core flow 테이블

ISSUE, PROJECT, USER, FIELD 테이블은 항상 만들어져요. 나머지 테이블은 해당 테이블 이름이 Enabled Tables 파라미터에 나열될 때만(또는 DELETED_ISSUE의 경우 삭제 추적이 활성화될 때만) 만들어져요. 자세한 내용은 Jira Cloud (Core) Ingestion Parameters을 참고해요.

테이블 활성화 내용
ISSUE 항상 Jira 이슈당 한 행. 컬럼 집합은 Issue Fields 구성에 의해 결정되며 커스텀 필드를 포함할 수 있음. 이슈 유형, 우선순위, 해결 상태, 상태 같은 필드는 Jira ID로 저장됨. 이름을 해석하려면 다음 조회 테이블과 조인함
PROJECT 항상 API 토큰 소유자에게 보이는 Jira 프로젝트당 한 행
USER 항상 수집 중 만난 Jira 사용자
FIELD 항상 동적 ISSUE 스키마를 구동하는 데 사용되는 Jira 이슈 필드의 메타데이터
CHANGELOG CHANGELOG 이슈 필드 변경 기록, 변경 기록 항목당 한 행
COMMENT COMMENT 이슈에 첨부된 코멘트, 코멘트당 한 행
ISSUE_REMOTE_LINK ISSUE_REMOTE_LINK 이슈에 첨부된 원격 링크
ISSUE_SECURITY_SCHEME ISSUE_SECURITY_SCHEME Jira 인스턴스에 정의된 이슈 수준 보안 스킴과 레벨
ISSUE_TYPE ISSUE_TYPE 이슈 유형 이름과 계층. ISSUE.ISSUE_TYPE = ISSUE_TYPE.ID로 ISSUE에 조인
ISSUE_VOTE ISSUE_VOTE 이슈별 투표 기록
ISSUE_WATCHER ISSUE_WATCHER 이슈별 워처 기록
PERMISSION PERMISSION 전역 및 프로젝트 권한 정의
PRIORITY PRIORITY 우선순위 이름. ISSUE.PRIORITY = PRIORITY.ID로 ISSUE에 조인
PROJECT_COMPONENT PROJECT_COMPONENT 각 프로젝트에 정의된 컴포넌트
PROJECT_VERSION PROJECT_VERSION 각 프로젝트에 정의된 릴리스 버전
RESOLUTION RESOLUTION 해결 상태 이름. ISSUE.RESOLUTION = RESOLUTION.ID로 ISSUE에 조인
STATUS STATUS 상태 이름과 범주. ISSUE.STATUS = STATUS.ID로 ISSUE에 조인
USER_GROUP USER_GROUP 사용자별 그룹 멤버십
WORKLOG WORKLOG 이슈의 시간 추적 항목
DELETED_ISSUE Deletes Fetch Strategy = AUDIT 감사 로그를 통해 추적되는, Jira에서 삭제된 이슈

Agile flow 테이블

다음 테이블들은 agile 플로우가 만들어요. 이 테이블들을 채우려면 core 플로우와 별도로 agile 플로우를 설치하고 실행해요. BOARD 테이블은 항상 만들어져요. 나머지 테이블은 agile 플로우 자체의 Enabled Tables 파라미터가 게이트 역할을 해요.

테이블 활성화 내용
BOARD 항상 API 토큰 소유자에게 보이는 Agile 보드
SPRINT SPRINT 수집된 모든 보드의 스프린트
BOARD_SPRINT SPRINT 보드-스프린트 매핑
BOARD_PROJECT BOARD_PROJECT 보드-프로젝트 매핑
BOARD_ISSUE BOARD_ISSUE 보드-이슈 매핑

커넥터 관리 컬럼(Connector-managed columns)

Jira API 응답에서 파생된 컬럼 외에도 커넥터는 다음 메타데이터 컬럼을 추가해요. _SNOWFLAKE_INSERTED_AT와 _SNOWFLAKE_UPDATED_AT는 모든 대상 테이블에 추가돼요. _SNOWFLAKE_DELETED는 소프트 삭제를 추적하는 테이블에만 추가돼요. 어느 테이블이 이 컬럼을 갖는지 보려면 Snowflake에서 대상 테이블을 검사해요.

컬럼 타입 용도
_SNOWFLAKE_INSERTED_AT TIMESTAMP_NTZ 커넥터가 행을 처음 삽입한 시각
_SNOWFLAKE_UPDATED_AT TIMESTAMP_NTZ 커넥터가 행을 마지막으로 업데이트한 시각
_SNOWFLAKE_DELETED BOOLEAN 소스 레코드가 더 이상 해당 Jira API 응답에 없으면 TRUE(예: Jira에서 삭제된 이슈, 이슈에서 제거된 코멘트). 행은 대상 테이블에 남아 있음. 소프트 삭제된 레코드를 제외하려면 _SNOWFLAKE_DELETED = FALSE로 필터링

워크플로우(Workflow)

  1. Jira Cloud 관리자는 다음 작업을 수행해요:
    • Jira 인스턴스 안에 API 토큰을 생성해요. 이 토큰은 커넥터가 인증에 사용해요. 스코프가 있는 토큰과 없는 토큰 모두 지원되지만, 세밀한 액세스 제어를 위해 스코프가 있는 토큰을 권장해요. 필요한 스코프는 활성화된 기능에 따라 달라져요. 자세한 내용은 Required API scopes을 참고해요.
    • 선택적으로, 삭제 추적이 필요한 경우 API 토큰 소유자가 감사 로그 엔드포인트에 접근할 수 있는 Administer Jira 전역 권한을 갖도록 해요.
  2. Snowflake 계정 관리자는 다음 작업을 수행해요:
    • 필요한 엔티티에 따라 core 플로우, agile 플로우, 또는 둘 다 설치해요.
    • 각 플로우를 구성해요:
      • Jira API 토큰과 이메일 주소를 제공해요.
      • Jira 인스턴스 URL을 지정해요.
      • core 플로우의 경우, Project Keys Filter로 수집을 특정 프로젝트로 선택적으로 필터링하고 수집할 이슈 필드를 구성해요.
      • Snowflake 계정의 데이터베이스와 스키마 이름을 설정해요.
    • Openflow 캔버스에서 플로우를 실행해요. 실행 시:
      • core 플로우는 프로젝트를 발견해 수집 상태 서비스에 등록하고, Enabled Tables에 나열된 이슈별 테이블(및 선택적으로 삭제된 이슈)과 함께 프로젝트 전체에서 이슈를 병렬로 가져오며, 독립적인 일정으로 작업 기록, 사용자, 사용자 그룹, 권한, 프로젝트 컴포넌트, 프로젝트 버전, 이슈 보안 스킴, ISSUE_TYPE, PRIORITY, RESOLUTION, STATUS 조회 테이블을 가져와요.
      • agile 플로우는 보드, 스프린트, 보드-프로젝트 매핑, 보드-스프린트 매핑, 보드-이슈 매핑을 가져와요.
  3. Snowflake 비즈니스 사용자는 JSON을 평탄화(flatten)할 필요 없이 표준 SQL로 대상 테이블을 직접 쿼리할 수 있어요.

Openflow 요구 사항

  • 최소 런타임 크기는 Small이에요. Enabled Tables에 테이블이 많으면 더 많은 프로세서가 동시에 실행되어 기본 Small 런타임 스레드 예산이 병목이 될 수 있어요. 그런 경우 Medium 런타임(또는 더 큰)으로 이동해요.
  • 커넥터는 멀티 노드 Openflow 런타임을 지원해요. 각 플로우의 상태 서비스는 클러스터 인식(cluster-aware)이며, 플로우 연결은 적절한 곳에서 로드 밸런싱을 사용하므로 작업이 사용 가능한 노드에 분산돼요. 여러 노드에서 실행하려면 자동 확장에 의존하지 말고 Min nodes를 대상 노드 수로 설정해 정적 클러스터 크기를 구성해요. 커넥터는 런타임이 스스로 노드를 자동 확장하게 할 만큼 충분한 지속적인 로드를 생성하지 않아요.
  • 프로젝트가 많은 Jira 인스턴스에는 멀티 노드 런타임을 권장해요. 프로젝트별 작업이 노드 전체에 분산되므로, 노드를 추가하면 커넥터가 병렬로 처리하는 프로젝트 수가 늘어나요. Min nodes 크기를 정할 때 프로젝트 수를 대략적인 기준으로 사용해요.
  • 커넥터는 주로 런타임 컴퓨팅 용량보다 Jira API 속도 제한(rate limits)에 의해 제한돼요. 런타임 크기를 Medium 이상으로 늘리거나 API 속도 예산이 지속할 수 있는 것보다 많은 노드를 추가해도 수집 속도가 개선될 가능성은 낮아요.
  • core 플로우와 agile 플로우는 같은 또는 별도의 Openflow 런타임에서 실행할 수 있어요. 같은 런타임에서 두 플로우를 모두 실행하면 Small로는 부족해요 — 최소한 Medium(또는 부하에 따라 더 큰)을 사용해요.

제한 사항(Limitations)

  • 이메일과 API 토큰을 사용한 기본 인증이 유일하게 지원되는 권한 부여 방법이에요. 커넥터는 API 토큰 소유자가 접근할 수 있는 데이터만 수집할 수 있어요.
  • AUDIT 전략을 통한 삭제 추적은 API 토큰 소유자가 Administer Jira 전역 권한을 가져야 해요. Jira 감사 로그는 보존 기간이 제한적이에요(보통 Jira Premium은 6개월, Free 또는 Standard 플랜은 더 짧음). 커넥터가 보존 기간보다 오래 일시 중지되면 삭제 이벤트를 놓칠 수 있어요.
  • ISSUE 테이블의 스키마 진화는 추가(단위) 방식만 지원돼요. 새 컬럼은 추가할 수 있지만, 컬럼 타입 변경이나 제거는 지원되지 않아요. Jira 커스텀 필드 타입이 바뀌면 커넥터 재배포가 필요할 수 있어요.
  • ISSUE 테이블 스키마는 동적이며 Issue Fields 구성에 따라 달라져요. 해석된 필드 집합에 포함되지 않은 필드는 로드되지 않고, 원시 JSON 폴백도 없어요. 이슈 유형, 우선순위, 해결 상태, 상태는 Jira ID로 저장돼요. ISSUE_TYPE, PRIORITY, RESOLUTION, STATUS 조회 테이블(기본 Enabled Tables 값에 있음)을 활성화하고 조인해 이름을 해석해요.
  • Project Keys Filter를 좁혀 프로젝트를 제거해도 대상 테이블에서 그 프로젝트의 행이 삭제되지는 않아요. 이전에 수집된 행은 그 자리에 남아 있고 더 이상 업데이트되지 않아요. 필터 변경 후 고아(orphaned) 행을 제거하려면 대상 테이블에서 수동으로 삭제해요.
  • Agile 데이터(보드, 스프린트, 보드 매핑)는 agile 플로우가 예약 실행될 때마다 완전히 다시 가져와요. 보드가 많은 Jira 인스턴스의 경우 API 사용량이 늘어날 수 있어요.
  • 각 커넥터 인스턴스는 Jira Cloud 사이트 하나에만 연결할 수 있어요.

다음 단계

더 알아보기 (Learn more)