March 25, 2023
  • The technical journey discusses the motivations, challenges, and technical options employed for warehouse schematization, particularly a change to the wire serialization format employed in Meta’s knowledge platform for knowledge interchange associated to Warehouse Analytics Logging.
  • Right here, we focus on the engineering, scaling, and nontechnical challenges of modernizing  Meta’s exabyte-scale knowledge platform by migrating to the brand new Tulip format. 
  • Schematization of information performs an essential function for a knowledge platform of this scale. It impacts efficiency, effectivity, reliability, and developer expertise at each stage of the information movement and improvement.

Migrations are exhausting. Furthermore, they change into a lot tougher at Meta due to:

  • Technical debt: Programs have been constructed over years and have numerous ranges of dependencies and deep integrations with different programs.
  • Nontechnical (mushy) elements: Strolling customers via the migration course of with minimal friction is a high quality artwork that must be honed over time and is exclusive to each migration.

Why did we migrate to Tulip?

Earlier than leaping into the main points of the migration story, we’d wish to take a step again and attempt to clarify the motivation and rationale for this migration.

Over time, the information platform has morphed into numerous varieties because the wants of the corporate have grown. What was a modest knowledge platform within the early days has grown into an exabyte-scale platform. Some programs serving a smaller scale started exhibiting indicators of being inadequate for the elevated calls for that had been positioned on them. Most notably, we’ve run into some concrete reliability and effectivity points associated to knowledge (de)serialization, which has made us rethink the way in which we log knowledge and revisit the concepts from first rules to deal with these urgent points.

Meta Tulip Migration
Determine 1: Excessive-level system diagram for analytics logging knowledge movement at Meta.

Logger is on the coronary heart of the information platform. The system is used to log analytical and operational knowledge to Scuba, Hive, and stream processing pipelines by way of Scribe. Each product and knowledge platform workforce interacts with logging. The information format for logging was both Hive Text Delimited or JSON, for legacy causes. The restrictions of those codecs are described in our earlier article on Tulip.

Enter Tulip serialization

To deal with these limitations, the Tulip serialization format was developed to switch the legacy destination-specific serialization codecs.

The migration final result — charted

The charts beneath graphically painting the migration journey for the conversion of the serialization format to Tulip to point out the progress at numerous phases and milestones.

Meta Tulip Migration
Chart 1: Logging schemas utilizing Legacy versus Tulip.
Meta Tulip Migration
Chart 2: Bytes logged per second by way of Legacy versus Tulip.

We are able to see that whereas the variety of logging schemas remained roughly the identical (or noticed some natural progress), the bytes logged noticed a major lower as a result of change in serialization format. The small print associated to format particular byte financial savings are tabulated within the part beneath.

Observe: The numbers in Chart 2 are extrapolated (to the general site visitors) primarily based on the precise financial savings noticed for the most important (by quantity) 5 logging schemas.


We wish to current our migration journey as two distinct phases with their very own views.

  1. The planning, preparation, and experimentation part: This part targeted on constructing technical options to assist validate the migration and permit it to proceed easily and effectively. Stringent automation for validation was constructed earlier than any migration was carried out. Information shoppers needed to be migrated earlier than the producers may very well be migrated. A small variety of white glove migrations had been carried out for crucial groups, and these supplied helpful insights into what can be essential within the subsequent part of the migration.
  2. The scaling part: On this part, the workforce constructed tooling and options primarily based on learnings from the sooner smaller scale migration. Contemplating non-technical views and optimizing for environment friendly folks interactions was crucial.

Planning and making ready for the migration journey

Designing the system with migration in thoughts helps make the migration a lot simpler. The next engineering options had been developed to make sure that the workforce was geared up with the required tooling and infrastructure help to change the wire format safely and to debug points that will come up in the course of the migration part in a scalable method.

The options roughly fell into the next buckets:

  1. Wire format associated: The main focus for this class of options was to make sure minimal to zero overhead when a format change of the serialization format is carried out. This concerned engineering the wire format for a clean transition in addition to arming numerous programs with format converters and adapters the place essential.
    1. Blended mode wire format
    2. Information consumption
  2. Testing, debugging, and rollout associated: This class of options concerned constructing rigorous testing frameworks, debugging instruments, and rollout knobs to make sure that points may very well be discovered proactively, and once they had been discovered within the reside system, the workforce was geared up to cease the bleeding and to debug and/or root-cause as swiftly as doable.
    1. Debugging instruments
    2. Shadow loggers
    3. Price limits and partial rollout

Blended mode wire format

Problem: How does one ease the migration and scale back danger by not requiring the information producer(s) and client(s) to change serialization codecs atomically?

Answer: When flipping a single logging schema over to make use of the brand new Tulip serialization protocol to put in writing payloads, supporting combined mode payloads on a single scribe stream was essential since it will be not possible to “atomically” change all knowledge producers over to make use of the brand new format. This additionally allowed the workforce to rate-limit the rollout of the brand new format serialization.

Blended mode wire format was essential for supporting the idea of shadow loggers, which had been used extensively for end-to-end acceptance testing earlier than a large-scale rollout.

The primary problem for combined mode wire format was not with the ability to change the prevailing serialization of payloads in both Hive Textual content or JSON format. To work round this limitation, each Tulip serialized payload is prefixed with the 2-byte sequence 0x80 0x00, which is an invalid utf-8 sequence.

Information consumption

Problem: In some programs, the Hive Textual content (or JSON) serialization format bled into the appliance code that ended up counting on this format for consuming payloads. It is a results of shoppers breaking via the serialization format abstraction.

Answer: Two options addressed this problem.

  1. Reader (logger counterpart for deserialization of information)
  2. Format conversion in shoppers

Reader (logger counterpart for deserialization of information)

Meta Tulip Migration
Determine 2: Reader for consuming combined mode knowledge.

Reader is a library that converts a serialized payload right into a structured object. Reader (like logger) is available in two flavors, (a) code generated and (b) generic. A reader object consumes knowledge in any of the three codecs — Tulip, Hive Textual content, or JSON — and produces a structured object. This allowed the workforce to change shoppers over to make use of readers earlier than the migration commenced. Utility code needed to be up to date to devour this structured object as a substitute of a uncooked serialized line. This abstracted the wire format away from shoppers of the information.

Conversion to legacy format(s) in shoppers

Meta Tulip Migration
Determine 3: Legacy format conversion in shoppers.

To be used instances the place updating the appliance code to devour a structured object was infeasible or too costly (from an engineering value viewpoint), we geared up the consuming system with a format converter that will devour the Tulip serialized payload and convert right into a Hive Textual content (or JSON) serialized payload. This was inefficienct by way of CPU utilization however allowed the workforce to maneuver ahead with the migration for a protracted tail of use instances.

Debugging instruments

“Debugging is twice as exhausting as writing the code within the first place. Subsequently, when you write the code as cleverly as doable, you’re, by definition, not sensible sufficient to debug it.” — Brian W. Kernighan

Meta Tulip Migration
Determine 4: The operation of loggertail, a CLI debugging software.

Problem: Allow simple visible testing and validation knowledge post-migration in a logging schema.

Answer: The loggertail CLI software was developed to permit validation of information post-migration in a selected logging schema’s scribe queue. Loggertail makes use of a generic deserializer. It queries the serialization schema for a named logging schema and makes use of it to decode the enter message. It then produces a human readable checklist of (area title, area worth) pairs and prints the information as a JSON object.

Shadow loggers

“Had been you the one who went into the field or the one who got here again out? We took turns. The trick is the place we might swap.” — “The Status”

Problem: Finish-to-end testing and verification of information logged by way of the brand new format.

Answer: Shadow loggers mimicked the unique logging schema, besides that they logged knowledge to tables that the logger workforce monitored. This constituted an end-to-end acceptance take a look at.

Along with the user-specified columns, a shadow logging schema had two further columns.

  1. Serialization format: Hive textual content or Tulip.
  2. Row ID: It is a distinctive identifier for the row, used to establish two similar rows that had been serialized utilizing completely different serialization codecs.

The shadow loggers logged a small fraction of rows to a shadow desk each time logging to the unique logging schema was requested. A spark job was used to research the rows in these tables and be certain that the contents had been similar for rows with the identical ID, however a distinct serialization format. This validation supplied the workforce with excessive confidence earlier than the rollout.

Meta Tulip Migration
Determine 5: How shadow logging works.

Price limits and partial rollout

Problem: How can we shortly include the bleeding in case of an issue in the course of the rollout of Tulip serialization to a logging schema?

Answer: Though validation by way of shadow loggers had been carried out for every logging schema being migrated, we needed to be ready for unexpected issues in the course of the migration. We constructed a fee limiter to scale back the chance and allow the workforce to swiftly cease the bleed.

Scaling the migration

With over 30,000 logging schemas remaining, the scaling part of the migration targeted on performing the migration, with it being self-serve and utilizing automation. One other essential side of the scaling part was guaranteeing that engineers would expertise as litte friction as doable.

Automation tooling

Problem: How does one select the schemas emigrate primarily based on the information shoppers of the corresponding scribe stream?

Answer: Every logging schema was categorized primarily based on the downstream shoppers of the corresponding scribe stream. Solely these logging schemas that had all supported downstream shoppers had been thought of able to devour the Tulip format.

Utilizing this knowledge, a software was constructed in order that an engineer simply wanted to run a script that will robotically goal unmigrated logging schemas for conversion. We additionally constructed instruments to detect potential knowledge loss for the focused logging schemas.

Ultimately, this tooling was run day by day by a cron-like scheduling system.

Nontechnical (mushy) elements

Problem: There have been quite a few nontechnical elements that the workforce needed to cope with whereas migrating. For instance, motivating finish customers to truly migrate and offering them help in order that they’ll migrate safely and simply.

Answer: For the reason that migration diverse in scale and complexity on a person, case-by-case foundation, we began out by offering lead time to engineering groups by way of duties to plan for the migration. We got here up with a reside migration information together with a demo video which migrated some loggers to point out finish customers how this needs to be achieved. As an alternative of a migration information that was written as soon as and by no means (or not often) up to date, a choice was made to maintain this information reside and consistently evolving. A help group and workplace hours had been set as much as assist customers in the event that they came upon any blockers. These had been notably helpful as a result of customers posted their experiences and the way they bought unblocked, which helped different customers to get issues transferring in the event that they encountered related points.


Making large bets such because the transformation of serialization codecs throughout all the knowledge platform is difficult within the quick time period, however it gives long-term advantages and results in evolution over time.

Designing and architecting options which can be cognizant of each the technical in addition to nontechnical elements of performing a migration at this scale are essential for fulfillment. We hope that we now have been in a position to present a glimpse of the challenges we confronted and options we used throughout this course of.


We wish to thank members of the information platform workforce who partnered with the logger workforce to make this mission successful. With out the cross-functional help of those groups and help from customers (engineers) at Meta, this mission and subsequent migration wouldn’t have been doable.