Migration Guide: Log Args v1.1

This guide is for users who consume gonemaster JSON results and are upgrading from pre-coherency output to the v1.1 log-args contract.

Scope:

  • CLI JSON outputs (--json, --json-stream)
  • Server result payloads (raw.entries[].args)

The entry envelope is unchanged:

  • timestamp, module, testcase, tag, level, args

The migration affects keys and value shapes inside args.

Biggest Changes

  1. ns no longer contains name/ip.
  • Old: ns: "ns1.example/192.0.2.53"
  • New: ns: "ns1.example", address: "192.0.2.53"
  1. Packed list strings were replaced by typed lists.
  • Old: ns_list, ns_ip_list, mailtarget_list, parent_addresses, zone_addresses
  • New: servers, addresses, mail_targets, parent_servers, zone_servers
  1. ASN fields are normalized.
  • Old: mixed usage (asn as string/int/list-like, asn_list as packed text).
  • New: asn is singular (int) and asns is a collection (array<int>).
  1. Query identity keys are canonical.
  • New standard: query_name, query_type, query_class
  • Legacy query aliases are not part of current runtime inventory.
  1. Legacy generic aliases were removed from current runtime inventory.
  • No longer emitted as runtime keys: name, server, ip, type, class, rrtype
  1. Contract versioning is documentation-based.
  • arg_schema is not emitted in runtime output.
  • v1.1 is documented in specs, not carried as an args field.
  1. Date/time string arguments are RFC3339.
  • If a tag emits a date/time string argument (for example RRSIG_EXPIRATION.date), it uses UTC RFC3339 (ISO 8601 profile).

Key Mapping (Old -> New)

Old keyNew keyNew type
ns (endpoint name/ip)ns + addressstring + string
ns_listserversarray<object>
ns_ip_listaddressesarray<string>
mailtarget_listmail_targetsarray<string>
parent_addressesparent_serversarray<object>
zone_addresseszone_serversarray<object>
asn_listasnsarray<int>
asn (collection semantics)asnsarray<int>
asn (singular semantics)asnint
type / rrtypequery_typestring
classquery_classstring
name (query context)query_namestring
serveraddress (or ns + address, tag-specific)string
ipaddressstring

servers-like object shape:

{"ns":"ns1.example","address":"192.0.2.53"}

Example Migration

Old:

{
  "Tag": "DS07_SIGNED_ON_SERVER",
  "Args": {
    "ns_list": "ns1.example;ns2.example"
  }
}

New:

{
  "Tag": "DS07_SIGNED_ON_SERVER",
  "Args": {
    "servers": [
      {"ns":"ns1.example"},
      {"ns":"ns2.example"}
    ]
  }
}

Old:

{
  "Tag": "WRONG_SOA",
  "Args": {
    "ns": "ns1.example/192.0.2.53",
    "name": "example.com.",
    "owner": "wrong.example."
  }
}

New:

{
  "Tag": "WRONG_SOA",
  "Args": {
    "ns": "ns1.example",
    "address": "192.0.2.53",
    "query_name": "example.com.",
    "owner": "wrong.example."
  }
}

Consumer Update Checklist

  1. Update deserializers to read typed collections:
  • servers as array<object>
  • addresses as array<string>
  • role-specific lists like parent_servers, zone_servers
  1. Stop splitting semicolon-delimited identity strings.
  • Use typed fields directly.
  1. Treat ns as name-only.
  • Read IP from address.
  1. Use canonical query keys.
  • query_name, query_type, query_class
  1. Normalize ASN handling in your consumer.
  • Read asns for multi-ASN outputs.
  • Treat asn as singular-only.

  1. Remove dependency on arg_schema.

  2. Add a temporary compatibility shim only if you must ingest historical data.

  • Map old keys to new keys at ingest time.
  • Prefer writing downstream state only in v1.1 key format.

References