Skip to content

Version History

  • Changes

    Read the outcomes and fixes in this release.

  • Upgrade

    Check migration guidance before changing an existing deployment.

Check release changes before choosing an upgrade.

Find the relevant version below and check breaking changes before scheduling an upgrade.

Next: Upgrade guidance

v2.6.0 (2025-07-21)

Added

  • Scheduled reconciliation keeps stored entries aligned with LDAP — IdentityScribe periodically verifies entries against the source directory.

    • Set either interval or cron to schedule the maintenance task. See the Configuration Reference for options and defaults.
    • One reconciliation runs after the initial sync and continuous search start, regardless of the schedule, to catch deletions that occurred during downtime.
    • Enable scheduled reconciliation if:
      • Your LDAP server has unreliable persistent-search delete notifications.
      • You need periodic consistency checks for compliance.
      • You experience frequent network partitions.
    • New Prometheus metrics for reconciliation:
      • scribe_reconciliation_entries_verified_total (counter): Number of entries verified as present in LDAP during reconciliation.
      • scribe_reconciliation_entries_deleted_total (counter): Number of entries deleted (synthetic deletes emitted) during reconciliation.
      • scribe_reconciliation_duration_seconds (summary/timer): Total time taken for a full reconciliation run.
      • scribe_reconciliation_last_run_timestamp_seconds (gauge): Unix timestamp of the last completed reconciliation run.
  • Maintenance tasks can run on a schedule — See the Configuration Reference for options and defaults.

    • These services support maintenance tasks:
      • Database: perform routine storage upkeep after startup.
        • New Prometheus metrics for database maintenance:
          • database_maintenance_duration_seconds (timer): Duration of each maintenance run.
          • database_maintenance_failed_total (counter): Number of failed maintenance runs.
          • database_maintenance_last_run_timestamp_seconds (gauge): Unix timestamp of the last attempted maintenance run.
      • Scribe: reconcile stored entries with the LDAP server.
        • The Scribe maintenance metrics are listed above.
  • Entry data compresses automatically — This reduces storage and network transfer size.

    • IdentityScribe selects the compression algorithm from the data characteristics.
    • Applications need no configuration changes.
    • Typical LDAP entries can use up to 70% less storage.
    • Prometheus metrics report compression effectiveness and cost.
  • LDAP entries keep their identity through restores and renames — Additional matching safeguards protect both initial and continuous synchronization, including rare directory restore and rename cases.

  • Prometheus scrapes return cached metrics — Metrics refresh on a regular interval so scrapes do not wait for collection work.

    • Set monitoring.prometheus.scrapeInterval to control the refresh interval. The default is 15 seconds.
    monitoring.prometheus.scrapeInterval = 15s

Fixed

  • License checks retry transient dependency failures — Connectivity failures involving LDAP or database services no longer crash the service immediately. IdentityScribe retries up to five times.
  • Attribute changes keep their configured casing — Change logs and event descriptions no longer lowercase attribute names, so downstream systems receive the configured names.
  • Reconciliation ignores unobserved operational attributes — It no longer reports false removals for attributes such as createTimestamp, modifyTimestamp, or entryUUID; history contains only changes IdentityScribe actually observed.

Breaking

  • BREAKING: Monitoring uses about half as many time series — dashboards and alerts that depend on the former formats may stop matching. Migration: update them to the formats below before upgrading, test them in staging, and monitor memory use after deployment.

    • Performance Impact
      • ~50% fewer metrics: Reduced from ~1,600 to ~800 total metrics
      • Memory: Rolling windows expire after 5 minutes, reducing memory use and keeping measurements current.
      • Cardinality: Service-transition and LDAP-search labels use fewer combinations.
      • Precision: Summary percentiles replace histogram approximations.
      • Storage: Fewer time series require less monitoring storage.
    • Monitoring Recommendations
      • Update dashboards to use new metric formats before upgrading
      • Test queries in a staging environment before using the new metrics in production.
      • Verify alerts that depend on histogram buckets before upgrading.
      • Monitor memory usage after upgrade (should decrease)

    Detailed Changes

    • Service Transition Metrics

      Before:

      service_transition_seconds{service="X",from="new",to="starting",...}
      service_transition_seconds{service="X",from="starting",to="running",...}
      service_transition_seconds{service="X",from="running",to="failed",...}

      After:

      service_transition_seconds{service="X",type="startup",...}
      service_transition_seconds{service="X",type="restart",...}
      service_transition_seconds{service="X",type="failure",...}

      Changes:

      • Removed: from and to tags (high cardinality)
      • Added: type tag with fixed categories (startup, restart, failure, shutdown)
      • Filtered: Startup noise transitions (new → starting)
      • Percentiles: Reduced from 5 to 2 percentiles (0.5, 0.95)

      Migration:

      • Update dashboards to use type instead of from/to tags
      • Categories: startup, restart, failure, shutdown
      Terminal window
      # Old query
      service_transition_seconds{from="starting",to="running"}
      # New query
      service_transition_seconds{type="startup"}
    • LDAP Search Metrics

      Before: Histogram with 50+ buckets

      channel_ldap_search_time_seconds_bucket{...,le="0.001"} 0
      channel_ldap_search_time_seconds_bucket{...,le="0.002"} 1
      [... 50+ buckets ...]

      After: Summary with selected percentiles

      channel_ldap_search_time_seconds{...,quantile="0.5"} 0.043
      channel_ldap_search_time_seconds{...,quantile="0.95"} 0.051
      channel_ldap_search_time_seconds{...,quantile="0.99"} 0.052

      Changes:

      • Format: Histogram → Summary
      • Percentiles: Reduced to 0.5, 0.95, 0.99 (high cardinality optimization)
      • Buckets: Removed all histogram buckets (50+ → 0)

      Migration:

      • Replace histogram_quantile() with direct quantile label access
      • Update SLI/SLO calculations to use summary percentiles
      Terminal window
      # Old query
      histogram_quantile(0.95, rate(channel_ldap_search_time_seconds_bucket[5m]))
      # New query
      channel_ldap_search_time_seconds{quantile="0.95"}
    • Processing Time Metrics

      Before: Histogram with SLO buckets

      scribe_processing_time_seconds_bucket{entryType="user",phase="diffing",le="0.001"} 5
      scribe_processing_time_seconds_bucket{entryType="user",phase="diffing",le="0.002"} 25
      [... many buckets ...]

      After: Summary with full percentiles

      scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.5"} 0.004
      scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.75"} 0.007
      scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.9"} 0.015
      scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.95"} 0.050
      scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.99"} 0.487

      Changes:

      • Format: Histogram → Summary
      • Percentiles: Added 0.5, 0.75, 0.9, 0.95, 0.99 (standard set)
      • Buckets: Removed all histogram buckets

      Migration:

      • Update queries to use quantile labels instead of histogram_quantile()
      • SLIs can now use direct percentile values
      Terminal window
      # Old query
      histogram_quantile(0.90, rate(scribe_processing_time_seconds_bucket[5m]))
      # New query
      scribe_processing_time_seconds{quantile="0.9"}
    • New Entry Codec Metrics

      Added new compression and entropy metrics:

      scribe_entry_encode_bytes{codec="lz4|zstd|none",kind="raw|compressed",quantile="0.5"} 1440
      scribe_entry_decode_bytes{codec="lz4|zstd|none",kind="raw|compressed",quantile="0.5"} 1440
      scribe_entry_encode_compression{codec="lz4|zstd",le="5.0"} 4
      scribe_entry_encode_entropy{le="25.0"} 137598

      Reports:

      • Encoded and decoded sizes by codec.
      • Compression thresholds at 85% and 95%.
      • Entropy distribution used for compression choices.
      • Percentiles 0.5, 0.75, 0.9, 0.95, 0.99.

v2.5.0 (2025-06-26)

Added

  • LDAP socket behavior is configurable — Environment variables and configuration properties can tune socket settings; the defaults suit production use.
  • Metrics scraping uses a dynamically balanced worker pool — Scrapes complete with less contention under changing load.

Fixed

  • LDAP presence searches no longer fail on an unsupported optimization — IdentityScribe now sends a valid search to the database.
  • Scribe event metrics use consistent labels — Every scribe_events_count series carries event, op, and target. Add, move, and delete events use "none" where op or target does not apply, preventing meter registration errors.

v2.4.0 (2025-06-25)

Added

  • Directory lookups are faster on large datasets — Additional database coverage reduces work for common entry searches.
  • Binary LDAP entry storage speeds synchronization and retrieval — Entries require less processing as they move between storage and channels.
  • Selective searches use faster execution choices — IdentityScribe adapts database requests to searches that match only a small part of the directory.
  • Initial synchronization avoids unnecessary lock contention — More work can proceed concurrently during the first sync.
  • Synchronization state checks complete faster — Continuous synchronization spends less time determining each entry’s current state.

Fixed

  • Startup counts as healthy while services initialize — Slow startup no longer causes a false health-check failure.
  • Health responses show the correct service name — Operators can identify the affected service directly from the response.
  • Routine monitoring disconnects no longer flood error logs — Client disconnects such as Broken pipe and Connection reset on metrics and health endpoints now log at debug level.
  • Scribe disconnect failures are easier to diagnose — Error handling and logs now preserve the useful failure context.
  • Restarts resume incremental synchronization — IdentityScribe no longer repeats the initial sync after every restart.

Breaking

  • BREAKING: Attribute sets are no longer supported — attributes that exist only in attributeSets stop being observed. Migration: move every listed attribute into the main attributes configuration before upgrading.
# Before (deprecated)
attributeSets = [
"uid, mail, displayName"
]
attributes = "cn sn"
# After (supported)
attributes = """
cn, sn
uid, mail, displayName
"""
  • BREAKING: Refresh-cache metrics were removed — dashboards and alerts that query them stop receiving data. Migration: remove these series from monitoring configuration:
    • scribe.entries.refresh.cache.count
    • scribe.entries.refresh.cache.time

v2.3.0 (2025-05-15)

Fixed

  • Initial synchronization uses bounded memory — Large imports complete faster and no longer fail when memory pressure rises.
  • Large LDAP responses no longer hit a message-size ceiling — Clients can receive entries that previously exceeded the limit.
  • Database connections are acquired more reliably — Pool handling no longer causes avoidable acquisition failures.
  • Memory and CPU metrics report more accurate values — Dashboards reflect resource use more closely.
  • Health endpoints respond faster — Both health and healthy checks require less work.
  • Routine logs are quieter and clearer — Normal activity uses appropriate levels and shorter messages.

Breaking

  • BREAKING: Built-in PostgreSQL metrics were removed — dashboards that rely on them stop receiving data. Migration: collect database metrics with the dedicated Prometheus Exporter.

v2.2.0 (2025-03-21)

Added

  • Entry-size categories improve storage monitoring — Operators can distinguish entry data by size and see the distribution in monitoring views.
  • Type-aware operations complete faster — Stored summaries reduce repeated work when IdentityScribe handles different entry types.

Fixed

  • Service startup and database upgrades coordinate correctly — Service orchestration now follows the database upgrade lifecycle.
  • The LDAP channel starts listening correctly — Clients can connect after channel startup.
  • Memory and CPU metrics report accurate values — Resource dashboards no longer show misleading measurements.
  • Health endpoints respond faster — Both health and healthy checks require less work.

v2.1.2 (2025-02-18)

Fixed

  • Attribute-set configuration rejects non-string values — Invalid elements fail validation with a configuration error.

v2.1.1 (2025-02-17)

Fixed

  • PostgreSQL TLS settings are applied correctly — Secure database connections now honor their configuration.
  • Referenced configuration files load correctly — Split configurations no longer fail while resolving included files.

v2.1.0 (2024-07-05)

Fixed

  • Relative configuration references resolve consistently — File and path references now load from relative locations.
  • Service TLS settings no longer leak into database configuration — ssl.enabled applies only to its intended service.

v2.0.0 (2024-03-30)

Breaking

  • BREAKING: v2 requires newly issued licenses — licenses from earlier releases are rejected. Migration: generate and install a license for v2 before starting the upgraded service.
  • BREAKING: Entry storage uses the v2 data model — tools that read the former database layout directly no longer work. Migration: let IdentityScribe migrate existing data during the upgrade and update direct readers to the uuid, dn, etag, createdAt, and updatedAt fields or, preferably, a supported channel.
  • BREAKING: Event timestamps use ISO 8601 UTC fields — consumers expecting createTimestamp or modifyTimestamp no longer find those properties. Migration: read createdAt and updatedAt and treat stored timestamps as UTC.
  • BREAKING: The checkpoint idle setting was renamed — the old key no longer controls checkpoint timing. Migration: replace ldap.idlePeriodForCheckpoint with ldap.idlePeriod; the default is 5 seconds.

Added

  • Stored entries expose UUID and distinguished-name fields — Direct database readers can access both identifiers without decoding entry data.
  • Operational attribute names adapt to the source directory — Product detection resolves the names used for entryUUID, createTimestamp, modifyTimestamp, and eTag.
  • Object-class attributes are always observed — objectClass and structuralObjectClass remain available to synchronization and searches.
  • Entry metadata and attribute values are stored separately — Dedicated attribute-value storage holds each entry’s data.
  • ETags use a longer hash — The extra hash bytes reduce the chance of collisions.
  • Distinguished-name lookups ignore case — Entries resolve even when the requested DN uses different casing.
  • Commit tracking survives transaction ID rollover — Long-running installations no longer risk collisions when database transaction identifiers wrap.
  • Continuous search no longer depends on modifyTimestamp or revision — This avoids sending a change notification for every update to an entry.
  • Attribute sets can be precomputed — Operators can define sets that reduce work when returning search results.
  • Partial-match attributes can use index coverage — Configured attributes accelerate substring and approximate searches.
  • LDAP is available as a data-access channel — Clients can query IdentityScribe through the LDAP protocol.
  • Local searches require complete observed data — IdentityScribe executes a search locally only when every filtered, sorted, and requested attribute is observed.
  • LDAP paging and sorting controls are supported — Clients can use Simple Paged Results, Server Side Sorting, and Virtual List View.
  • LDAP subordinate-subtree scope is supported — subordinate_subtree (3) includes descendants at any depth but not the base entry itself, as described in draft-sermersheim-ldap-subordinate-scope.
  • Approximate and extensible DN filters are supported — These extend the existing and, or, not, equality, substring, greaterOrEqual, lessOrEqual, and present filters:
    • approximate matches a close value; for example, (givenName~=John) can match John or Jon.
    • extensible dn match includes the entry DN in matching; for example, (ou:dn:=Engineering) matches an ou value of Engineering beneath the base DN.
  • ETags change with observed attribute values — Any change to an observed value produces a new etag.
  • Operations unavailable locally forward to the source LDAP server — Clients keep access to upstream capabilities.
  • Prometheus exposes detailed service metrics — Operators can collect them from the Prometheus endpoint.
  • Read-only channel instances can run without transcription — For load balancing and similar deployments, start IdentityScribe with one of these options:
    • the --readonly (-r) flag
    • IDENTITY_SCRIBE_READONLY=1, IDENTITY_SCRIBE_READONLY=true, or IDENTITY_SCRIBE_READONLY=yes environment variable
    • IDENTITY_SCRIBE_TRANSCRIBE_ENABLED=0, IDENTITY_SCRIBE_TRANSCRIBE_ENABLED=false, or IDENTITY_SCRIBE_TRANSCRIBE_ENABLED=no environment variable

Fixed

  • Empty operations no longer create events — History contains only events with an actual change.
  • Automatic storage ranges no longer skip a boundary — Generated ranges now include the correct records.
  • Renaming an entry updates its naming attributes — The new distinguished name and naming values stay consistent.
  • Every environment setting accepts both supported input forms — Use an IDENTITY_SCRIBE_<...> environment variable or a -D<...> command-line property; for example, IDENTITY_SCRIBE_READONLY=1 identity-scribe or identity-scribe -DREADONLY=1.
  • Licenses work with clustered LDAP servers — A license remains valid across nodes in the same LDAP cluster.