사용 가능 플랜: Entry, Enterprise Advanced

Mattermost v12.0부터 Mattermost는 메시지 내용이 사용자 또는 연동에 전달될 때마다 감사 로그 항목을 기록할 수 있습니다. 이 기록을 통해 특정 메시지가 어떤 사용자에게 어떤 방식으로 전달되었는지 확인할 수 있습니다.

전달 기록은 일반 감사 로그 기록이며, 기존 감사 로깅 파이프라인을 통해 구성한 감사 로그 대상에 기록됩니다.

시작하기 전에#

게시물 전달 감사 로깅에는 다음 항목이 모두 필요합니다.

• Mattermost Enterprise Advanced 라이선스.
• 기본적으로 비활성화되어 있는 기능 플래그 MM_FEATUREFLAGS_POSTDELIVERYTRACKING. 기능 플래그를 활성화한 후에는 서버를 재시작하세요.
• System Console > Compliance > Audit Logging > Advanced Logging에서 구성한 고급 감사 로깅.
• 고급 감사 로그 구성에서 audit-delivery 로그 수준을 처리하는 감사 로그 대상.

감사 로그 대상 구성#

전달 기록은 ID가 104인 audit-delivery 로그 수준으로 기록됩니다. 다른 감사 로그 수준과 달리 audit-delivery는 기본 제공 감사 로그 파일 대상에 기록되지 않으므로 ExperimentalAuditSettings.FileEnabled를 활성화해도 전달 기록이 수집되지 않습니다. 대신 ExperimentalAuditSettings.AdvancedLoggingJSON에 수준 104를 처리하는 대상을 추가하세요. 사용 가능한 대상 유형과 옵션은 고급 로깅을 참조하세요.

전달 기록의 양이 다른 감사 기록을 압도하지 않도록 전용 대상을 사용하는 것을 권장합니다. 아래 예시는 전달 기록을 별도 파일에 기록하며, 파일은 100MB마다 순환하고 기록하는 동안 메모리에 최대 10,000개의 기록을 버퍼링합니다.

{
    "post-delivery-audit": {
        "type": "file",
        "format": "json",
        "levels": [
            { "id": 104, "name": "audit-delivery" }
        ],
        "options": {
            "filename": "./logs/post-delivery-audit.log",
            "max_size": 100,
            "max_age": 0,
            "max_backups": 0,
            "compress": true
        },
        "maxqueuesize": 10000
    }
}

게시물 전달 감사 로깅이 활성화되어 있는데 audit-delivery 수준을 처리하는 감사 로그 대상이 없으면 구성은 유효한 상태로 유지되고 전달 기록은 폐기되며, Mattermost는 시작 시와 구성이 변경될 때마다 다음 경고를 기록합니다.

DeliveryTrackingSettings.Enable is enabled but no configured audit log target consumes the audit-delivery level; post delivery audit records will be discarded. Add a target for the level via ExperimentalAuditSettings.AdvancedLoggingJSON.

게시물 전달 감사 로깅 활성화#

System Console에서 Site Configuration > Data Spillage Handling > Post Delivery Audit Logging으로 이동하여 게시물 전달 감사 로깅을 활성화하고 전달을 기록할 채널을 선택합니다. 절차는 게시물 전달 감사 로깅을, 해당하는 config.json 설정과 환경 변수는 사이트 구성 설정을 참조하세요.

기록 형식#

각 전달은 postDelivered 감사 로그 기록으로 저장됩니다. 기록의 status는 항상 success입니다.

메시지 수신자는 기록의 행위자이며 actor.user_id에 있습니다. 별도의 수신자 필드는 없습니다. 이를 통해 행위자별로 기록을 그룹화하여 「이 사용자에게 무엇이 전달되었는가」에 답할 수 있습니다. 플러그인이나 아웃고잉 웹훅으로의 전달에는 사람 수신자가 없으므로 actor.user_id가 비어 있으며, 대신 meta.plugin_id 또는 meta.webhook_id가 해당 연동을 식별합니다.

meta 객체는 무엇이 어떻게 전달되었는지 식별합니다. REST API 요청에서 생성되는 감사 기록과 달리 전달 기록의 meta에는 api_path나 cluster_id가 없습니다.

Mattermost REST API를 통해 사용자에게 전달된 메시지:

{
    "timestamp": "2026-08-12 14:03:11.482 Z",
    "event_name": "postDelivered",
    "status": "success",
    "actor": {
        "user_id": "hx4k9m2qzbfytr7wn6cbd3jvse",
        "session_id": "",
        "client": "",
        "ip_address": ""
    },
    "meta": {
        "post_id": "xpw97hf6kfncirzhqisb5sym7e",
        "channel_id": "pfis7ycuy78o7m3zebajmxqeuo",
        "mechanism": "product"
    },
    "error": {}
}

같은 메시지가 사람 수신자 없이 플러그인에 전달된 경우:

{
    "timestamp": "2026-08-12 14:03:11.509 Z",
    "event_name": "postDelivered",
    "status": "success",
    "actor": {
        "user_id": "",
        "session_id": "",
        "client": "",
        "ip_address": ""
    },
    "meta": {
        "post_id": "xpw97hf6kfncirzhqisb5sym7e",
        "channel_id": "pfis7ycuy78o7m3zebajmxqeuo",
        "mechanism": "plugin",
        "plugin_id": "com.mattermost.example-plugin"
    },
    "error": {}
}

모든 Mattermost 감사 로그 기록에 공통으로 포함되는 필드는 감사 로그 JSON 스키마를 참조하세요.

페이로드 필드#

postDelivered 기록의 meta 객체에는 다음 필드가 포함됩니다. 수신자는 meta에 없으며, 수신자는 기록의 행위자로서 actor.user_id에 있습니다.

전달 메커니즘#

mechanism 필드는 메시지 내용이 수신자에게 도달한 방식을 기록합니다. 항상 다음 일곱 가지 값 중 하나입니다.

기록되지 않는 항목#

다음은 기록되지 않습니다.

• 메시지 작성자: 사용자는 자신이 작성한 메시지에 대한 전달 기록을 받지 않습니다.
• 시스템 메시지와 임시 메시지.
• 읽으면 삭제되는 메시지.
• 다이렉트 메시지와 그룹 메시지: 이 채널은 모든 채널에서 전달을 기록하는 경우에도 대상이 되지 않습니다.
• 일반 푸시 알림: 메시지 내용이 포함되지 않은 푸시 알림은 아무것도 기록하지 않습니다. 푸시 알림이 ID만 보내도록 구성된 경우 기기가 내용을 가져올 때 전달이 기록됩니다.
• 데이터베이스에서 읽는 플러그인: 플러그인 API나 메시지 후크가 아니라 데이터베이스에서 직접 메시지를 읽는 플러그인은 관찰할 수 없으므로 기록되지 않습니다.

봇과 아웃고잉 웹훅이 게시한 메시지는 다른 메시지와 동일하게 기록됩니다.

전달 기록 해석#

Mattermost는 각 수신자에게 전달된 메시지마다 하나의 항목을 일괄 처리 없이 기록합니다. 메시지 100개를 반환하는 채널 로드는 기록 100개를 생성하며, 연결된 채널 멤버 40명에게 브로드캐스트된 새 메시지는 기록 40개를 생성합니다.

전달 기록은 메시지를 본 사람의 중복 제거된 목록이 아니라 추가 전용 이벤트 스트림입니다. 사용자가 채널을 다시 방문할 때마다 같은 메시지 페이지가 다시 전달되므로 사용자, 메시지, 메커니즘의 동일한 조합이 반복됩니다. 각 기록은 고유한 타임스탬프를 가진 실제 전달입니다.

수신자, 메시지, 전달 메커니즘별로 항목을 하나씩 얻으려면 actor.user_id, meta.post_id, meta.mechanism을 기준으로 중복을 제거하고, 각 그룹에서 가장 이른 타임스탬프를 해당 메커니즘의 첫 전달로 취합니다. 같은 메시지를 둘 이상의 메커니즘으로 받은 수신자(예: push 후 product)는 메커니즘마다 항목이 하나씩 있습니다.

이를 메시지가 도달한 고유 사용자 목록으로 줄이려면 키에서 meta.mechanism을 제외하고 actor.user_id와 meta.post_id만으로 중복을 제거하세요.

전달 기록을 다룰 때는 다음 사항에 유의하세요.

• 전달은 읽음의 증거가 아닙니다: 기록은 Mattermost가 수신자가 읽을 수 있는 엔드포인트로 메시지 내용을 전송했다는 의미입니다. 누군가 읽었다는 의미는 아닙니다. 메시지 내용을 포함하도록 이메일 알림을 구성한 사용자는 Mattermost를 한 번도 열지 않았더라도 전달로 기록됩니다.
• 기록이 완전하다고 보장되지 않습니다: 감사 로깅은 비동기로 동작하므로 서버가 비정상적으로 중지되면 메모리 대기열에 남아 있던 기록은 손실됩니다. 정상 종료 시에는 대기열을 비웁니다. 이는 모든 감사 로그 수준에 적용되는 기존 감사 로깅 동작입니다.
• 퍼머링크 미리보기는 미리보기 대상 메시지를 따릅니다: 퍼머링크 미리보기 전달의 기록 여부는 미리보기를 포함한 메시지의 채널이 아니라 미리보기되는 메시지의 채널에 따라 결정됩니다. 기록 대상 채널에 있는 메시지의 미리보기는 기록 대상이 아닌 채널에서 렌더링되더라도 기록됩니다. 이렇게 하지 않으면 기록 대상 메시지를 다른 채널에 퍼머링크로 붙여 넣어 읽을 수 있게 됩니다. Mattermost는 퍼머링크 미리보기를 한 단계까지 렌더링하므로 한 단계까지 기록됩니다.