Logging

Logging

UxmDiscordSync has three independent logging systems, all delivered via Discord webhooks:

System	What It Logs
Audit Log	Account links, unlinks, rank syncs, boost claims
Chat Log	Minecraft player chat messages
Join/Leave Log	Minecraft player joins/leaves and Discord member joins/leaves

---

Setup: Creating a Webhook

Each log system uses its own webhook URL. To create one in Discord:

1. Open the target channel → Edit Channel → Integrations → Webhooks → New Webhook.
2. Give it a name and optionally a custom avatar.
3. Click Copy Webhook URL.
4. Paste the URL into logging.yml.

---

Configuration

All logging settings live in logging.yml:

audit-log:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."

  # Embed templates for each event type
  events:
    link:
      color: "#57F287"
      title: "Account Linked"
      fields:
        - name: "Minecraft"
          value: "%player_name% (%player_uuid%)"
        - name: "Discord"
          value: "%discord_name% (%discord_id%)"
        - name: "Server"
          value: "%server_name%"
    unlink:
      color: "#ED4245"
      title: "Account Unlinked"
    rank-sync:
      color: "#5865F2"
      title: "Rank Synchronised"
    boost-claim:
      color: "#FF73FA"
      title: "Boost Reward Claimed"

chat-log:
  enabled: false
  webhook-url: "https://discord.com/api/webhooks/..."
  format: embed               # "embed" or "plaintext"
  max-messages-per-minute: 30

  # Do not log messages that start with these strings
  ignore-prefixes:
    - "/"
    - "!"

join-leave-log:
  minecraft:
    join:
      enabled: true
      webhook-url: "https://discord.com/api/webhooks/..."
      format: embed
      color: "#57F287"
      title: "Player Joined"
      message: "**%player_name%** joined the server."
    leave:
      enabled: true
      webhook-url: "https://discord.com/api/webhooks/..."
      format: embed
      color: "#ED4245"
      title: "Player Left"
      message: "**%player_name%** left the server."
  discord:
    join:
      enabled: true
      webhook-url: "https://discord.com/api/webhooks/..."
      message: "**%discord_name%** joined the Discord server."
    leave:
      enabled: true
      webhook-url: "https://discord.com/api/webhooks/..."
      message: "**%discord_name%** left the Discord server."

---

Audit Log

Events Logged

Event	Trigger
LINK	Player successfully links their account
UNLINK	Player or admin unlinks an account
FORCE_LINK	Admin uses /uxmdiscordsync forcelink
FORCE_UNLINK	Admin uses /uxmdiscordsync forceunlink
RANK_SYNC	Rank synchronization completes for a player
BOOST_CLAIM	Player successfully claims a boost reward

Embed Fields

Each audit event embed can include any combination of:

Placeholder	Description
%player_name%	Minecraft username
%player_uuid%	Minecraft UUID
%discord_name%	Discord username
%discord_id%	Discord user ID
%server_name%	Server name
%timestamp%	Event timestamp
%roles_added%	Discord roles added (rank sync)
%roles_removed%	Discord roles removed (rank sync)

---

Chat Log

Logs every qualifying Minecraft chat message to a Discord webhook.

Message Filtering

Messages are skipped if they:

• Start with any string in ignore-prefixes
• Come from a player with the uxmdiscordsync.chat.bypass permission

Format Options

embed — Each message is a Discord embed with the player's name and face as author.

plaintext — Messages are sent as plain text: [PlayerName] message content

Rate Limiting

The max-messages-per-minute setting limits how many webhook calls the logger makes per minute. If exceeded, excess messages are dropped. Discord's own rate limit is 30 requests per minute per webhook.

---

Join/Leave Log

Minecraft Events

Logs when a player joins or leaves the Minecraft server.

Available placeholders in messages:

Placeholder	Description
%player_name%	Minecraft username
%player_uuid%	Minecraft UUID
%server_name%	Server name
%online_players%	Players online after this event

Discord Events

Logs when a member joins or leaves the Discord server itself.

Available placeholders:

Placeholder	Description
%discord_name%	Discord username
%discord_id%	Discord user ID
%member_count%	Total Discord member count after this event

---

Webhook Rate Limiting

The plugin enforces a minimum 1-second delay between consecutive webhook calls to avoid hitting Discord's rate limits (30 requests/minute per webhook). In practice, events are queued and sent sequentially with this delay.

If you need multiple log types to go to the same webhook URL, you can reuse the same URL across different sections — the rate limiter tracks per-URL.