--- title: "Introducing entities: Real-time debugging for individual users" slug: "entities" blurb: "Today we are announcing a major feature addition to bitdrift Capture: *entities*. Entities bring the real-time debugging and observability superpowers of bitdrift Capture to individual end-users. This feature is truly customer support on steroids. Read on for the full scoop." metaDescription: "" cover: url: "/assets/posts/entities/feature-cover-entities-desktop@1x.webp" alt: "" socialThumbnail: url: "/assets/posts/entities/feature-cover-entities-desktop@1x.webp" alt: "" coverVideo: url: "/assets/posts/entities/entities.mp4" alt: "Introducing Entities" author: - "matt" tags: - "feature" publishedDate: "2026-06-17T15:13:39.171Z" modifiedDate: "2026-06-17T15:13:39.171Z" --- ## Observing individuals vs. populations Before diving into the new entities feature, let’s first recap how bitdrift [Capture](https://bitdrift.io/feature/performance-centric) works. Capture couples a real-time control plane with device local storage in order to provide [1000x the data when you need it and none when you don’t](https://blog.bitdrift.io/post/1000-x-the-telemetry). It does this by spooling telemetry data locally on the device and running finite state machines against it in order to determine what actions to take (e.g., emit a synthetic metric, capture a full user session, start distributed tracing, and so on). The main unit of investigation in Capture is the [*workflow*](https://docs.bitdrift.io/product/workflows/overview.html). A workflow is an incredibly powerful tool that allows you to run a query directly against your user population, whether small or large, for behavioral investigations. Technically, your population could be narrowed to an individual user (by matching on a user ID or some other ID specific to the entity that is being investigated). We’ve repeatedly seen customers take this approach to debug individual end-user reported issues since the launch of Capture 2.5 years ago. While it “works”, the experience is subpar for two reasons: 1. Capture’s real-time configuration delivery system is built to handle massive scale. ([As we noted recently, our SDK is present in over 1 billion app installs](https://blog.bitdrift.io/post/bitdrift-turns-1-billion)). **Sending a workflow that should only ever match a single user or device to every device is incredibly inefficient** and also takes many minutes to reach all connected devices due to incremental delivery. 2. The lack of a first-class *entity ID* throughout the system means that there is **no built-in way to clearly show all entity- specific data** such as sessions, issues, online history, devices used, and so on. As a result, Capture users have dealt with a clunky experience trying to answer some very simple questions, like: * **For a given entity ID, what sessions are there?** What crashes have they experienced? How often are they online? How many devices do they use? * **I want to capture all session data for a particular entity the next time they are online** or debug them in real time if they’re online now. How do I do it? * My CEO keeps calling me to complain that the app is broken. **How do I track VIP users so I can always understand their app experience?** (No joke, this is a real question that almost every app team faces, constantly.) The answer until now has been to write a workflow that matches a log specific to the user of interest and hope for the best next time they are online. The fact that our customers have stuck with us for 2.5 years, despite the limitations of this approach for per-entity debugging, told us that this is a high value use-case that needed a dedicated in-product treatment. ## Introducing entities Entities List As of today, entities are a first class citizen within Capture that span the entire product. The *only* work required is to call a new SDK API, *[setEntityID()](https://docs.bitdrift.io/sdk/features/entity-id)*, when the on-device entity ID changes. The entity ID can be any ID that is useful as a unique identifier such as customer ID, point of sale device ID, and so on. Once this is done, a bunch of magical things happen automatically within Capture: 1. ***Every*** **session** created on the device where the entity ID is known will be reported to the control-plane, including sessions that are not yet uploaded. This alone is a huge improvement because now it’s possible to understand whether a session ever existed at all, whether it was triggered but not uploaded due to daily limits, etc. 2. **Every crash** is also indexed by entity ID. 3. **Every connection** to our SaaS that the entity makes is indexed, allowing us to track online history, IP-based location data, and estimate the next time we expect the entity to be online. 4. We also keep track of ***real-time connection state***. This means that we can tell you in real time whether the entity is currently online, and if so, some very powerful support and debugging features are immediately unlocked. The screen shot above shows all of this in action. For a particular entity we show: * Recent sessions * Recent crashes * Known devices * IP location history * Online time, current online status, and if offline the estimated time the entity will be next online given historical patterns. Entities List Possibly most importantly, we also allow recording all session data in the [ring buffer](https://bitdrift.io/feature/ring-buffer) the next time the entity is online, and sending a notification to a notification group when the recording happens. This completely removes the need for bespoke workflows that customers used in the past to capture this data. Returning to the entity page will show the session recording status and allow captured sessions to be easily opened in the timeline. Sessions captured this way are not subject to daily workflow limits, making it super easy to always get as much information as needed about individual entities. ## Known entities / VIPs Entities Workflows Along with general entity support, we are also introducing the concept of “known entities,” which are tailored towards the VIP use case. Or, as we mentioned above, the CEO calling and yelling at you use case. Known entities are entity IDs registered with friendly names in the system, unlocking additional functionality. * They are **searchable by friendly names** in the UI. * More importantly, we are introducing a **new workflow matcher** that matches *only* if the target device is currently a registered known entity. This allows creating workflows specific to the VIP set including VIP-specific charts and so on. If it’s not already clear, we also have been scarred by the CEO calling us and yelling at us many, many times, and we’ve got you covered. 😂 ## Live entity debugging Entities Live Debugging If all of the above wasn’t enough, we are also making it trivial to start a live debugging session for currently online entities. This works the same way our existing workflow-based live debugging does under the hood, streaming logs, network requests, and state directly from the device, but it's scoped to a person instead of a query. That distinction matters more than it sounds: a support engineer doesn't think in terms of "find me a workflow that matches this user." They think "this specific person is having a problem right now, let me go look." Live entity debugging matches that mental model directly. In practice, this collapses what used to be a multi-step, multi-minute process (write workflow, deploy, wait, hope it's still relevant when it lands) into something closer to opening a remote terminal to a single device. Combined with the recording feature described above, this means you can either watch what's happening live, or queue up a full capture for the next time the entity reconnects. Is your CEO calling you right now and yelling at you? You can debug while you are getting yelled at. For real. ## Privacy At bitdrift we take privacy *extremely* seriously. While the above features may sound scary from a privacy perspective, here’s how we mitigate the risk. First, **bitdrift *never* stores the raw entity ID.** We only ever store a hash of the entity ID. This means that having access to the raw bitdrift data *does not* provide a direct reverse mapping to the originating entity ID. There are downsides to this, such as we cannot show you the original ID in the UI, we cannot allow fuzzy searching over IDs, and so on, but we feel the privacy needs are greater. The location data we show is *only* based on IP address. **We *never* capture or send device location.** This means that the location can be wildly inaccurate in some cases, but most of the time it is good enough to at least understand regional patterns. ## Join us for the future of observability Entities are available today for all customers looking to understand and debug individual users, not just populations. New and existing customers can [contact us](https://bitdrift.io/signup) to learn more. With Capture, bitdrift is changing the mobile observability game by adding a control plane and local storage on every mobile device. Get extremely detailed telemetry when you need it, and none when you don’t. If lack of entities was keeping you away, now is the time to give us a try\! Interested in learning more? Here are some options: * [Get in touch](https://bitdrift.io/contact-us) for a demo. * Check out [the sandbox](https://bitdrift.io/sandbox) to see what working with Capture is like. * Start a [free trial](https://bitdrift.io/signup) to dive right into the product. We can’t wait to see what you think. --- ## Frequently asked questions ### What are entities in bitdrift Capture? Entities are a feature in bitdrift Capture that lets teams track and debug individual end-users or devices, rather than only querying across a population. Once a team calls the `setEntityID()` SDK method, Capture indexes that entity's sessions, crashes, devices, IP-based location history, and real-time online status. ### How is debugging an entity different from using a workflow? Workflows query across a user population and can be narrowed to match a single user, but doing so requires writing and deploying a rule to the entire device fleet, which is inefficient at scale. Entities remove this step. Once an entity ID is set, that user's data is automatically tracked, and live debugging or session recording can be triggered directly from the entity page with no workflow required. ### Does bitdrift store raw entity IDs? No. bitdrift only stores a hash of the entity ID, never the raw value. This means the original ID cannot be reverse-engineered from bitdrift's stored data, though it also means raw IDs can't be displayed or fuzzy-searched in the UI. ### What is a "known entity" in bitdrift? A known entity is an entity ID registered with a friendly name, typically used for tracking VIP users. Known entities are searchable by name in the UI, and a dedicated workflow matcher lets teams build workflows, charts, and alerts scoped specifically to the known entity (VIP) population. ### Can I capture session data for a user who isn't currently online? Yes\! Capture can be configured to record a user's full session data automatically the next time that entity comes online, triggering a notification sent when the recording completes. This removes the need for a custom workflow and isn't subject to the daily limits that apply to workflow-based captures.