Version History
- Changes
Read the outcomes and fixes in this release.
- Upgrade
Check migration guidance before changing an existing deployment.
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
intervalorcronto 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.
- Set either
-
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.
- New Prometheus metrics for database maintenance:
- Scribe: reconcile stored entries with the LDAP server.
- The Scribe maintenance metrics are listed above.
- Database: perform routine storage upkeep after startup.
- These services support maintenance tasks:
-
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.scrapeIntervalto control the refresh interval. The default is 15 seconds.
monitoring.prometheus.scrapeInterval = 15s - Set
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, orentryUUID; 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:
fromandtotags (high cardinality) - Added:
typetag 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
typeinstead offrom/totags - Categories:
startup,restart,failure,shutdown
Terminal window # Old queryservice_transition_seconds{from="starting",to="running"}# New queryservice_transition_seconds{type="startup"} - Removed:
-
LDAP Search Metrics
Before: Histogram with 50+ buckets
channel_ldap_search_time_seconds_bucket{...,le="0.001"} 0channel_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.043channel_ldap_search_time_seconds{...,quantile="0.95"} 0.051channel_ldap_search_time_seconds{...,quantile="0.99"} 0.052Changes:
- 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 directquantilelabel access - Update SLI/SLO calculations to use summary percentiles
Terminal window # Old queryhistogram_quantile(0.95, rate(channel_ldap_search_time_seconds_bucket[5m]))# New querychannel_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"} 5scribe_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.004scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.75"} 0.007scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.9"} 0.015scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.95"} 0.050scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.99"} 0.487Changes:
- 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
quantilelabels instead ofhistogram_quantile() - SLIs can now use direct percentile values
Terminal window # Old queryhistogram_quantile(0.90, rate(scribe_processing_time_seconds_bucket[5m]))# New queryscribe_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"} 1440scribe_entry_decode_bytes{codec="lz4|zstd|none",kind="raw|compressed",quantile="0.5"} 1440scribe_entry_encode_compression{codec="lz4|zstd",le="5.0"} 4scribe_entry_encode_entropy{le="25.0"} 137598Reports:
- 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.
- Performance Impact
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_countseries carriesevent,op, andtarget. Add, move, and delete events use"none"whereoportargetdoes 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 pipeandConnection reseton 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
attributeSetsstop being observed. Migration: move every listed attribute into the mainattributesconfiguration 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.countscribe.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.enabledapplies 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, andupdatedAtfields or, preferably, a supported channel. - BREAKING: Event timestamps use ISO 8601 UTC fields — consumers expecting
createTimestampormodifyTimestampno longer find those properties. Migration: readcreatedAtandupdatedAtand treat stored timestamps as UTC. - BREAKING: The checkpoint idle setting was renamed — the old key no longer controls checkpoint timing. Migration: replace
ldap.idlePeriodForCheckpointwithldap.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, andeTag. - Object-class attributes are always observed —
objectClassandstructuralObjectClassremain 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
modifyTimestamporrevision— 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
substringandapproximatesearches. - 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, andpresentfilters:approximatematches a close value; for example,(givenName~=John)can matchJohnorJon.extensible dn matchincludes the entry DN in matching; for example,(ou:dn:=Engineering)matches anouvalue ofEngineeringbeneath 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, orIDENTITY_SCRIBE_READONLY=yesenvironment variableIDENTITY_SCRIBE_TRANSCRIBE_ENABLED=0,IDENTITY_SCRIBE_TRANSCRIBE_ENABLED=false, orIDENTITY_SCRIBE_TRANSCRIBE_ENABLED=noenvironment variable
- the
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-scribeoridentity-scribe -DREADONLY=1. - Licenses work with clustered LDAP servers — A license remains valid across nodes in the same LDAP cluster.