Skip to main content

Release Notes

version 0.48.6

  • add --flat compiler option

version 0.48.5

  • Compiler retries if it cannot initially connect to The default is 2 retries (waiting 5 seconds in between). This can be overridden with the --retries command line option.

version 0.48.4

  • Compiler generates better client side logging messages for asynchronous errors
  • Compiler prints out all fatal metric/audience errors, rather than the first it comes across
  • More stuff moved off of the critical path for the external handler

version 0.48.1

  • Allow "in" predicate to be used on integer types

version 0.48.0 (2024-02-08)

  • @is_default now checks the actual values as opposed to just seeing that we are running in control
  • bandits now use outperformance instead of just raw metrics to balance arms, making the objective function more stationary

version 0.47.1 (2024-02-08)

  • fix hash collision

version 0.47.0 (2024-01-15)

  • Internal maintenance release of database and UI components.

version 0.46.0 (2024-01-04)

  • Added a traffic allocation chart to the bandit experiment analysis screen.
  • improved bandit arm selection procedure wrt new arms without any traffic
  • improved some logging wrt impression not found errors
  • add support for LLM generated bandit arms

version 0.45.0 (2023-12-11)

  • The iserver can now optionally read and update values in redis. See redis
  • The iserver can now optionally filter out bots from being loaded into your warehouse with the --bot-detector argument. The bot list is refreshed on every release from
  • FDL now supporting categorizing the user agents into higher level dimensions. See redis
  • Added ability for the snippet to update input button text.
  • Improved snippet selector error handling and reporting.

version 0.44.1 (2023-12-06)

  • Fixed issue with custom path prefix override in the iserver.

version 0.44.0 (2023-12-05)

  • The experiment analysis page has been updated to consistently sort metrics. The main experiment metric will be listed first and the guardrail metrics will follow in alphabetical order.
  • You can integrate Causal with your website without programming by using the script tag.
  • The impression server now supports standing up > 1 environment per server instance.
  • You can now write audience filters on timestamps
  • Session Start Time is exposed as a value you can use to specify audiences

version 0.43.2 - 0.43.5 (2023-11-28)

  • Bandit copy testing updates

version 0.43.1 (2023-11-20)

  • The sample directive can discard data at the end of a session.
  • New K-armed bandits experiments allow you to add and remove variants at any time while the experiment is running
  • NDCG metrics implemented on back end
  • iserver is now running under JDK 17

version 0.42 (2023-10-04)

  • The compiler will now display the CLI help message if no fdl files are passed in.
  • The compiler will now error (or reduced to a warning) if a new non-nullable field is added to a feature without a default value. Also, if an existing field's type is changed from nullable to non-nullable without a default value.
  • Review page has been redesigned as the new sunset-features page. It's now easier to deprecate features/events/fields
  • High priority experiment setting now available to toggle on experiment detail and analyze pages. Allows an experiment to take priority over other conflicting experiments.

version 0.41 (2023-09-14)

  • The IServer's /signal URI will now return a 400 error if the payload is missing. In earlier releases the error code was 500.
  • New "until" option for elapsed directive
  • New /sync iserver uri to force a resync of configuration data with
  • The IServer's connections to will reconnect after 1 hour if there is no activity.
  • Newly redesigned experiments analysis page
  • The compiler will now only error when FDL changes are breaking a metric or an audience in the case when that metric or audience are in production use and the environment being updated is a staging environment (one that will eventually roll into production)
  • The compiler has a new --warn-on-error flag that will override the above error into a warning. Note that this is the same functionality as the --warn flag, but is more self descriptive.
  • NDCG now available as a metric in the metric builder. The backend changes to calculate the metric will be in the next release.
  • no_log can be applied to FDL object fields

version 0.40.1 (2023-08-23)

  • fix issue with unsubstituted variable in published pom for the parser.

version 0.40.0 (2023-08-22)

  • Impression servers will now send telemetry data to Causal so we can better support customers. Collected data includes errors rates and http request counts to API endpoints. This can be disabled by setting the system property -Diserver.enable-counter-collection=false or by exporting an environment variable: ISERVER_ENABLE_COUNTER_COLLECTION=false.
  • The metric table in Athena has a new boolean column called external_metric.
  • Offline events allow you to record events that don't happen on your site, and define experiment metrics that take those into account.
  • useFeature adds new return type "OFF". Please see this article for details.
  • The TypeScript client now assumes SSG as the default page type. If this is not correct for you, please change to SSR or CSR as appropriate by setting it in initCausal. See this article for more details.
  • Metrics based on proportion of events are now available.

version 0.39.0 (2023-07-19)

  • Entity tagging allows you to tag features, experiments, metrics, and audiences so you can organize them in the tools UI.
  • Experiment results can now be filtered based on specific events or feature-attributes. (currently only equality is supported)
  • The impression server is now using Spring Boot. This will make some more metrics available through OpenTelemetry. The underlying web server is still Jetty.
  • Made it easier to copy data from the event viewer.

The APIs will now be more strict about when you access fields in a feature or session. In plugins, if you try to access a value before it is set, you will get an IllegalStateException. Also some values, that cannot be calculated until the session ends will not have getters anymore


The compilers mustache interface has changed slightly. (for java code, not mustache templates) io.causallabs.mustache.Feature.getSessionKeys used to return aCollection\<FeatureColumn>in the new version it returnsCollection \<? extends FeatureColumn>`

version 0.38.0 (2023-07-07)

  • iOS client API
  • External metrics allow you to use metrics calculated in your data warehouse for Causal experiments
  • API only external outputs allow you to log data through the external output api calls
  • signalled events will attempt to create a session if the session is not found, as opposed to dropping the event
  • You can specify that a metric improves when it decreases now. The analytics page has a better treatment for decreasing metrics.
  • support for persistent variants across sessions. This is useful for longer term metrics that are used in Causal inference, and experiment across different surfaces like email and online.
  • removed IP address from automatically generated session fields

Version 0.37.1 (2023-06-28)

  • java client correctly drops errors when ignoreMissingImp is set
  • java client returns futures from async calls in case the caller would like to check exceptions
  • iserver now sorts sessions before dumping the file, in preparation for new downstream ETL work

Version 0.37.0 (2023-06-23)

  • iserver now exposes telemetry metrics and traces
  • warehouse table documentation is now available in the web tools
  • ip address calculation now uses (x-forwarded-for) header
  • fix stat display when pval is zero
  • back end optimizations
  • misc bug fixes and security updates

Version 0.36.0 (2023-06-08)

  • Option to automatically add event views to the glue catalog as Athena queries

Version 0.35.6 (2023-05-25)

  • Improve speed of analytics page

Version 0.35.4 (2023-05-25)

  • Fix for ETLs reading log files from older versions of the impression server for impression based metrics

Version 0.35.3 (2023-05-25)

  • Fix to numeric equality filters on audiences

Version 0.35.0 (2023-05-18)


This release deprecates the impression_ids column in the data warehouse feature impression tables. The column still exists in this release but will be removed in future version. Use the new column impressions instead, which includes both the id for the impression and the time the impression occurred.

  • Add experiment triggers. You can now specify an event that should occur before collecting data for an experiment. Before this change, any data would count towards an experiment as soon as one of the features in the experiment created an impression. Now, in addition to this, you can specify an event that must occur before the data is logged. This is useful in cases where the experiment will not effect the user until a certain thing happens on your front end. IE, the treatment scrolls into view, or the treatment pops up after a certain time.
  • new constructedNewCache method in typescript tells if you are creating a new session when running in the browser.
  • add created by / last updated fields to the experiments page
  • warn when features in an experiment use different audiences.
  • new Hello Causal developer tutorial
  • Show feature impression rate in the Tools UI
  • ETL can now run inside your own clusters instead of Causal's
  • the compiler warns when it encounters a deprecated item in the FDL file.
  • the compiler can accept code blocks inside a feature in any order (ie, now it does not matter if your 'args' block is after your 'output' block)
  • New FDL tab in Tools UI lets you view each environment's current FDL file
  • various bugfixes

Version 0.34.9 (2023-05-02)

  • Reduce load on tools UI when multiple impression servers are connected in the same environment. Results in a zippier UI.
  • Fix some bugs with the command endpoint
  • New "impression_end" option for elapsed directive

Version 0.34.1 (2023-04-18)

  • new optional command endpoint for the impression server, currently used to manually kick off an ETL
  • fixed issue where feature overrides were not forcing the feature on for features without outputs.
  • Updated AWS client and transfer manager to 2.20.47
  • fix issue where Glue catalog would not sync old partitions correctly if fields were added to an event
  • fix speed issue downloading environment information for the compiler from tools.
  • fix error messages when clients signal an event using a schema that the iserver does not know about yet.
  • improve performance of some tools pages with optimized database access
  • make the is_default, variant_name, and variant_id directives apply to the current impression server environment as opposed to production

Version 0.33.0 (2023-04-05)

  • new hello-causal getting started guide and support
  • new is_default, variant_name, and variant_id directive to support output value provenance
  • remove setters for non-plugin output from java API.
  • Disable end experiment button for readonly users

Version 0.32.0 (2023-03)

  • 95% confidence interval in the experiment analysis screen is now of the difference
  • new --race-delay option allows you to configure how long the impression server waits for an impression to show up
  • Completed experiments now show the correct control values
  • fix an issue where a link to tools would end you in the wrong place if you were not originally logged in
  • make compiler error messages more clear when FDL is incompatible with an audience or metric
  • fix an issue where QA overrides get lost if a session expires.

Version 0.31.1 (2023-03-23)

  • Fix a bug in which the impression server would NPE if a QA override was set for a feature not defined in the iserver's environment

Version 0.31.0 (2023-03-22)

  • Add option to event viewer to terminate your session.
  • Make audiences available ASAP, so audiences that do not reference feature outputs are available for experiment selection on that same feature.
  • Display experiment errors on the experiment's analysis page
  • Added Open Telemetry to the impression server
  • better logging for CI/CD webhook errors
  • new impression server endpoint to retrieve session values
  • mutable history end times are now set to the session end time
  • fix compiler issue when generating code for an abstract feature
  • Shrink TS code in the generated APIs
  • Fix issue where the iserver would not be able to set QA values if it was bounced in the middle of a session
  • Drop invalid partitions in the data warehouse if incompatible FDL is forced through
  • Added onImpression callback to CausalOptions with improved ActiveVariant semantics, and new RequestedFeature functionality.

Version 0.30.0 (2023-02-23)

  • Add useFeature React hook
  • Support undefined and conditional types (in useFeature and useQuery)
  • Don't send empty override values (caused impression server error message)
  • fix issue where iserver would lose QA settings when a session expires
  • Fix issue where the tools ui would register the same experiment error twice

Version 0.29.9 (2023-02-21)

  • Fix issue where new event_id value was not showing up in WarehouseColumn.get\<>Type methods

Version 0.29.8 (2023-02-20)

  • Fix an issue where external outputs that were not completely rolled up would should up on the client with their values already set

Version 0.29.7 (2023-02-17)

  • Fix an issue with the Java compile target generating unparseable multiline strings that would cause compile errors

Version 0.29.6 (2023-02-16)

  • Make the link modal available for all types

Version 0.29.5 (2023-02-14)

  • Fix a issue were the eventTime written on the events was the event processing time and not the time the impression server received the event
  • Add a unique "eventId" field to all events
  • Fix an issue where the compiler would generate an incomprehensible error if you tried to use a reserved word to define an FDL enum value
  • Fix an issue where the compiler would issue a warning for a metric if the FDL didn't support it, even if the metric was archived

Previously, the fields returned by io.causallabs.mustache.Event.getEventColumns did not return the built in event columns impression_id and event_time. They now do. If you'd like to filter out these columns in your scripts, you can use the io.causallabs.mustache.Event.Column.fromFdl method, which returns false for system defined fields.

Version 0.29.4 (2023-02-10)

  • Don't scroll screen when editing multi screen values
  • Correctly end experiment on "roll to control" so later duplication works
  • Fix issue where QA doesn't show up if a user has multiple devices on different version of the FDL
  • Improve some logging messages
  • return immediately a 200 status code if there is a session event that is the target of an abstract event signal

Version 0.29.2 (2023-02-08)

  • Show messages if variant and control are identical

  • Make non prod missing FDL messages a warning

  • If no devices registered, "Send to my devices" becomes "Register QA Device" and goes to QA page

  • Improve field formatting and alignment

  • Bugfixes

Version 0.29.1 (2023-02-07)

  • Bugfixes

Version 0.29.0 (2023-02-06)


The plugin api changed in version 0.28.6. Impression servers >=0.28.6 must have plugins that are compiled with a compiler version >=0.28.6.

  • Added metric tables to mustache template generation
  • add support for deprecating event fields, events, and enum types
  • Bugfixes and speed improvements

Version 0.28.6 (2023-01-31)


The plugin api is not back compatible for this version. Impression servers >=0.28.6 must have plugins that are compiled with a compiler version >=0.28.6.

  • new interfaces io.causallabs.runtime.Impression and io.causallabs.runtime.ImpressionEvent expose more functionality to the interfaces in the plugin API
  • add support for marshalling Causal objects as JSON

Version 0.28.5 (2023-01-31)

  • Add new "environment" field to the session that can be used in audience creation

Version 0.28.4 (2023-01-30)

  • Always indicate in feature panel when a QA override is active
  • Correctly handle "revert to control" for QA overrides
  • Push control value updates out intra-session for registered devices
  • Fix issue where all control value updates were not going through intra-session when QA is turned off
  • Performance improvements

Version 0.28.3 (2023-01-27)

  • Fix issue with iserver notification causing excessive load and slowness in the database

Version 0.28.1 (2023-01-24)

  • add a row to the variant table that represents control.

Version 0.28.0 (2023-01-23)

  • new mutable value layout has mutable values stored as their last know values. History is in another column called NAME_history
  • new @no_log directive
  • new option to copy an existing experiment so you don't have to start from scratch creating a similar one
  • Allow metric description to be edited after metric is published
  • Improved formatting and deduplicate experiment errors in status screen
  • Improve performance when adding variants and enabling event viewer
  • better default handling when processing event schemas that were logged using a different version
  • UI improvements
  • bugfixes

Version 0.27.0 (2022-12-22)

  • add guardrail metrics to experiment metadata table
  • add 'audiences' column to session table
  • add regex filter to metrics and audiences (iservers must be upgraded to 0.27.0 before this will match)
  • add more data to user mustache contexts
  • add ability to substitute in compiler's classpath for running with non-standard application jars

Version 0.26.3 (2022-12-12)

  • Fix issue with @elapsed getting ignored for session events

Version 0.26.2 (2022-12-08)

  • Fix issue with not adding causal-x headers to signal network calls

Version 0.26.1 (2022-12-08)

  • Fix issue with percent audience predicate on nullable types

Version 0.26.0 (2022-12-07)

Version 0.25.3 (2022-11-25)

  • fix impression count dump

Version 0.25.2 (2022-11-16)

  • fix issue with experiment failing with @per metrics

Version 0.25.0 (2022-11-16)

  • type @hints
  • Sorting and filtering the experiments list page
  • Conflicting experiments can run concurrently. Variants will be chosen at runtime. A particular session can only be selected into one of the conflicting experiments. Split traffic warnings will be issued for conflicting experiments.
  • user defined FDL templates (see the io.causallabs.runtime.mustache package)
  • fix to variant exposure in TS api
  • add support to log iserver calls in typescript API
  • break plugin API eval call into fill and onImpression to support server side typescript caching
  • Support for calculating statistical significance of guardrail metrics
  • python pex for aws setup, instead of docker

Version 0.24.0 (2022-10-28)

  • Max and Min metric aggregators
  • Typescript cache filling support
  • @elapsed directive
  • Keep alives
  • Experiment support for @per metrics
  • Improvements for archiving metrics
  • Faster AWS setup procedure
  • "percent traffic" metric and audience filter
  • improvements to experiment analytics pages
  • update libraries to fix new dependency vulnerabilities

version 0.23.6 (2022-10-12)

version 0.23.0 (2022-10-04)

  • documentation for making your own impression server image

  • export active variant information to typescript AP


  • remove loading state for CSR -> CSR transitions

  • add ability to archive metrics

  • documentation for integrating with Gitlab

  • document @default_off

  • several UI bugfixes

  • null handling in UI

  • improve backward compatibility for metrics and audiences

version 0.22.0 (2022-09-27)

  • "send to my devices" will force the feature on if necessary
  • Plugins can now prevent the session from being logged: docs
  • Metrics / Audience use new non-propagating null semantics
  • new "starts with" filter
  • Metrics / Audiences can be defined on a session start event.
  • fix bug where you couldn't end an experiment in the error state

version 0.21.2 (2022-09-25)

  • Add logging of several more events to the event viewer including
    • plugin exceptions
    • unresolved impressions
    • disabled features
    • unresolved events

version 0.21.1 (internal release)

  • regenerate the tools UI FDL view on webhook start

version 0.21.0 (2022-09-23)

  • Extra API checks for setting externals
  • Guardrail Metrics support for experiments
  • Feature History shows audience changes. The data was being recorded correctly, just not displayed.
  • Metrics path spec can be configured (upon request) to use a specific environment, rather than the lowest ranked environment
  • Fix bug with Analyze page crashing
  • Fix bug not being able to delete experiment that had errors
  • Fix letting user save invalid values to a feature
  • Fix to TS client when FDL contains userId arg
  • remove intra-session variant tables
  • add SSR and Cache Stats example for Typescript
  • fix compiler when running on a machine without JDK installed

version 0.20.0 (2022-09-15)

  • Improved typescript documentation
  • Hide typescript private items from autocomplete
  • Ruby / Java don't signal errors when signalling features not deployed on iserver yet
  • event viewer handles undeployed impressions and events

Version 0.19.0 (2022-09-12)

  • Added several predicates for audience and metric creation: null, not null, does not contain, one of, not one of
  • Fixed issues with Ruby code generation
  • Compiler improvements that fixed some formatting
  • New Azure documentation
  • New Plugin debug options and maven hosted impression server
  • Fix issue with ruby connecting to the impression server over https
  • Various bugfixes
  • Typescript client supports SSR caching and cache transfer to CSR (breaking change)
  • Typescript client supports reporting for cache hits and misses

Version 0.18.0

  • Compiler supports Ruby client API
  • Support for low privileged users to use debug tools
  • Typescript support for enumeration value deprecation
  • Typescript support for field level errors
  • Typescript support for x-causal headers
  • Typescript generate enum as TS enums instead of string (breaking change)
  • Typescript fixes for SSR (breaking change)
  • Support for event plugins (
  • Support for Snowflake as a target for Causal data
  • Support for Microsoft Azure as an impression server log target
  • Support for OpenID Connect providers
  • Asynchronous signals that have errors also log the error on the client
  • Fix to metric calculation when filtered by certain session arguments
  • Various other bugfixes