감사 이벤트 개발 지침
이 안내서는 감사 이벤트의 작동 방식과 새로운 감사 이벤트를 구현하는 방법에 대한 개요를 제공합니다.
감사 이벤트란?
감사 이벤트는 GitLab 소유자 및 관리자가 애플리케이션 전반에서 수행된 중요한 작업 기록을 볼 수 있는 도구입니다.
감사 이벤트로 적합하지 않은 것들
어떤 이벤트가 감사 이벤트를 트리거할 수 있지만 모든 이벤트가 그렇지는 않습니다. 일반적으로 감사 이벤트로 적합하지 않은 이벤트는 다음과 같습니다:
- 특정 사용자에게 연결할 수 없는 이벤트.
- 관리자 또는 소유자 persona에게 특별히 흥미로운 것이 아닌 이벤트.
- 제품 기능 채택을 위한 정보 추적.
- 계획되지 않은 항목에 대한 토론 페이지에서 다루는 정보.
감사 이벤트에 대한 질문이 있다면 @gitlab-org/govern/compliance
에 문의하여 이벤트에 가장 적합한 감사 이벤트 또는 다른 접근 방법을 확인하세요.
감사 이벤트 스키마
감사 이벤트를 메트릭하려면 다음 속성을 제공해야 합니다:
속성 | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name
| String | false | 감사할 동작 이름. 이벤트 유형 정의을 나타냅니다. 오류 추적에 사용됨 |
author
| User | true | 변경을 작성한 사용자. 내부 사용자일 수 있음. 예를 들어, 비활성 프로젝트 삭제 감사 이벤트는 GitLab-Admin-Bot 이 작성함.
|
scope
| User, Project, Group 또는 Instance | true | 감사 이벤트가 속한 범위 |
target
| Object | true | 감사 대상 객체 |
message
| String | true | 동작을 설명하는 메시지 (번역되지 않음) |
created_at
| DateTime | false | 동작이 발생한 시간. 기본값은 DateTime.current
|
새로운 감사 이벤트를 메트릭하는 방법
- 새로운 감사 이벤트에 대한 YAML 유형 정의를 작성하세요.
- 작업 블록을 전달하여
Gitlab::Audit::Auditor.audit
를 호출하세요.
새로운 방식으로 감사 이벤트를 메트릭하는 것은 다음과 같이 폐기되었습니다:
-
ee/lib/ee/audit/
에 새로운 클래스 생성 및AuditEventService
확장 - 성공적인 동작 이후
AuditEventService
호출
Gitlab::Audit::Auditor
서비스를 사용하여 다음과 같은 두 가지 방법으로 감사 이벤트를 메트릭할 수 있습니다.
여러 이벤트를 기록하는 블록 사용
이 방법은 이벤트가 호출 스택 내부에 발생할 때 사용할 수 있습니다.
예를 들어, 사용자가 Merge Request 승인 규칙을 업데이트할 때 여러 감사 이벤트를 기록할 수 있습니다. 이 사용자 흐름의 일부로 우리는 승인자와 승인 그룹에 대한 변경 사항을 모두 감사하고 싶습니다. 초기화 서비스(예: MergeRequestRuleUpdateService
)에서 execute
호출을 다음과 같이 감쌀 수 있습니다:
# 초기화 서비스 내에서
audit_context = {
name: 'update_merge_approval_rule',
author: current_user,
scope: project_alpha,
target: merge_approval_rule,
message: '승인 규칙을 업데이트하려고 시도함'
}
::Gitlab::Audit::Auditor.audit(audit_context) do
service.execute
end
모델(예: ApprovalProjectRule
)에서 모델 콜백(예: after_save
또는 after_add
)에서 감사 이벤트를 푸시할 수 있습니다.
# 모델 내에서
include Auditable
def audit_add(model)
push_audit_event('보안 규칙에 승인자 추가함')
end
def audit_remove(model)
push_audit_event('보안 규칙에서 승인자 제거함')
end
이 방법은 비동기적인 동작이거나 여러 프로세스를 거치는 동작을 지원하지 않습니다(예: 백그라운드 작업).
표준 메서드 호출을 사용하여 하나의 이벤트를 기록하는 방법
이 방법은 단일 감사 이벤트를 기록할 수 있으며 더 적은 이동 컴포넌트이 관련됩니다.
if merge_approval_rule.save
audit_context = {
name: 'create_merge_approval_rule',
author: current_user,
scope: project_alpha,
target: merge_approval_rule,
message: '새로운 승인 규칙 생성함',
created_at: DateTime.current # 비동기로 생성된 감사 이벤트에 시간을 사전 지정할 때 유용함.
}
::Gitlab::Audit::Auditor.audit(audit_context)
end
데이터 양 고려사항
각 감사 이벤트는 데이터베이스에 지속됩니다. 따라서 새로운 감사 이벤트가 생성하는 데이터 양과 생성 속도를 고려하세요. 데이터베이스에 많은 데이터를 프로덕션하는 새로운 감사 이벤트의 경우 스트리밍 전용 감사 이벤트를 추가하는 것을 고려하세요. 이에 대한 질문이 있다면 이슈 또는 Merge Request에서 자유롭게 @gitlab-org/govern/compliance/backend
에 문의하세요.
감사 이벤트 장치 흐름
감사 이벤트를 장치하는 두 가지 방법에는 다른 흐름이 있습니다.
여러 이벤트를 기록하는 블록 사용
Gitlab::Audit::Auditor
에서 작업 블록을 감싸서 (즉, author
, scope
, target
) 객체를 기록할 수 있습니다.
Auditable
mixin을 가진 상호작용하는 클래스에서 Gitlab::Audit::EventQueue
를 통해 감사 이벤트를 추가하는 추가 감시가 필요합니다.
EventQueue
는 SafeRequestStore
를 통해 로컬 스레드에 저장되어 나중에 Gitlab::Audit::Auditor
에서 감사 이벤트를 기록할 때 추출됩니다.
표준 메서드 호출을 사용하여 하나의 이벤트를 기록하는 방법
이 방법은 보다 간단한 흐름을 가지며 EventQueue
및 로컬 스레드에 의존하지 않습니다.
데이터베이스에 기록하는 것 외에 이러한 이벤트들은 로그 파일에도 기록됩니다.
이벤트 유형 정의
새로운 감사 이벤트는 GitLab의 감사 가능한 모든 이벤트에 대한 단일 정보원을 포함하는 config/audit_events/types/
또는 ee/config/audit_events/types/
에 저장된 유형 정의를 가져야 합니다.
새로운 감사 이벤트 유형 추가
새로운 감사 이벤트 유형을 추가하려면:
- YAML 정의를 만드세요. 다음 중 하나를 사용할 수 있습니다:
-
bin/audit-event-type
CLI를 사용하여 YAML 정의를 자동으로 생성합니다. -
config/audit_events/types/
에 파일 이름이 이벤트 유형과 일치하는 새 파일을 매뉴얼으로 만듭니다. 예를 들어, 사용자가 프로젝트에 추가될 때 트리거되는 이벤트 유형에 대한 정의는config/audit_events/types/project_add_user.yml
에 저장될 수 있습니다.
-
- 파일에 schema에 부합하는 내용을 추가합니다. 이 schema는
config/audit_events/types/type_schema.json
에 정의됩니다. -
name
에서 정의된Gitlab::Audit::Auditor
로의 모든 호출이 파일에서 정의된name
을 사용하는지 확인합니다.
스키마
필드 | 필수 | 설명 |
---|---|---|
name
| 예 | 파일 이름과 일치해야 하는 유일한 소문자 및 밑줄로 표시된 이벤트 유형을 설명합니다. |
description
| 예 | 해당 이벤트가 어떻게 트리거되는지에 대한 사람이 읽을 수 있는 설명 |
group
| 예 | 이 감사 이벤트를 소개한 그룹의 이름. 예를 들어, manage::compliance
|
introduced_by_issue
| 예 | 이 유형의 추가를 제안한 이슈 URL |
introduced_by_mr
| 예 | 이 새로운 유형을 추가한 MR URL |
milestone
| 예 | 이 유형이 추가된 마일스톤 |
saved_to_database
| 예 | 이벤트를 데이터베이스와 JSON 로그에 유지할지 여부를 나타냅니다 |
streamed
| 예 | (구성된 경우) 이벤트를 외부 서비스로 스트리밍해야 하는지 표시합니다 |
문서 생성
감사 이벤트 유형 문서는 자동으로 생성되어 게시됩니다. GitLab 문서 사이트로.
새로운 감사 이벤트 유형을 추가하는 경우 다음 gitlab:audit_event_types:compile_docs
Rake 작업을 실행하여 문서를 업데이트하세요:
bundle exec rake gitlab:audit_event_types:compile_docs
문서가 최신 상태인지 확인하려면 gitlab:audit_event_types:check_docs
Rake 작업을 실행하세요:
bundle exec rake gitlab:audit_event_types:check_docs
이벤트 스트리밍
그룹
또는 프로젝트
가 엔티티인 모든 이벤트는 감사 로그에 기록되며 하나 이상의 이벤트 스트리밍 대상지로 스트리밍됩니다. 엔티티가:
-
그룹
인 경우, 이벤트는 그룹의 루트 상위 조상의 이벤트 스트리밍 대상지로 스트리밍됩니다. -
프로젝트
의 경우, 이벤트는 프로젝트의 루트 상위 조상의 이벤트 스트리밍 대상지로 스트리밍됩니다.
GitLab 데이터베이스에 저장되지 않는 스트리밍 전용 이벤트를 추가할 수 있습니다. 스트리밍 전용 이벤트는 주로 많은 양의 데이터를 생성하는 작업에 사용됩니다. 예는 이 MR를 참조하세요. 이 기능은 현재 빠르게 개발 중입니다. 기능 개발에 대한 업데이트는 상위 Epic에서 확인하세요.
I18N 및 감사 이벤트 :message
속성
의도적으로 감사 이벤트 메시지를 번역하지 않습니다. 번역된 메시지는 데이터베이스에 저장되어 사용자의 로캘 설정에 관계없이 사용자에게 제공됩니다.
예를 들어, 인증된 사용자의 로캘을 사용하여 감사 이벤트 메시지를 기록하고 해당 메시지를 해당 대상의 잘못된 언어로 외부 스트리밍 대상에 스트리밍할 수 있습니다. 사용자는 그것을 혼란스러워할 수 있습니다.