Add assertion IDs that will be included in production log statements for fail and hardAsserts #8313

MarkDuckworth · 2024-06-12T17:42:42Z

In the Firestore SDK, error messages are removed from fail(message) and hardAssert(condition, message) statements during the build. Removal of error messages is performed to reduce bundle size, however this comes at a cost to usability. Specifically, this means that production error messages can be unhelpful.

Here's an example of a production error message today (without this change):

FIRESTORE (1.2.3) INTERNAL ASSERTION FAILED: Unexpected state

"Unexpected state" is the same reason given for 130+ error conditions after the detailed error messages have been stripped.

To improve debuggability of error messages, this PR adds a numeric assertion ID to each fail and hardAssert statement. These numeric IDs are unique and will not be removed from the build output. The full error message will still be removed during the build, but the assertion IDs introduced with this change will give customers and support more information to debug the output.

Here's and example of a production error message after this change is applied:

FIRESTORE (1.2.3) INTERNAL ASSERTION FAILED: Unexpected state (ID: 0x2e4a) CONTEXT: {"example": "relevant JSON serialized state of the application when the assertion failed."}

Scripts:
yarn assertion-id:new - Create a new unique ID
yarn assertion-id:check - Check for duplicate and invalid id formatting
yarn assertion-id:find <ID> - Find an existing ID and the error message associated with it
yarn assertion-id:list - list all of the existing IDs and their error messages

…d of removing error messages.

changeset-bot · 2024-06-12T17:42:47Z

🦋 Changeset detected

Latest commit: 833f972

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@firebase/firestore	Patch
firebase	Patch
@firebase/firestore-compat	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2024-06-12T17:44:46Z

Changeset File Check ✅

No modified packages are missing from the changeset file.
No changeset formatting errors detected.

google-oss-bot · 2024-06-12T19:22:51Z

Size Report ¹

Affected Products

@firebase/data-connect
Type Base (933ba9d) Merge (8d4a221) Diff
browser 21.4 kB 21.4 kB +5 B (+0.0%)
main 23.6 kB 23.7 kB +51 B (+0.2%)
module 21.4 kB 21.4 kB +5 B (+0.0%)
@firebase/firestore
Type Base (933ba9d) Merge (8d4a221) Diff
browser 382 kB 384 kB +2.48 kB (+0.6%)
main 591 kB 594 kB +3.22 kB (+0.5%)
module 382 kB 384 kB +2.48 kB (+0.6%)
react-native 382 kB 384 kB +2.47 kB (+0.6%)
@firebase/firestore-lite
Type Base (933ba9d) Merge (8d4a221) Diff
browser 113 kB 114 kB +984 B (+0.9%)
main 155 kB 157 kB +1.42 kB (+0.9%)
module 113 kB 114 kB +984 B (+0.9%)
react-native 113 kB 114 kB +984 B (+0.9%)

`bundle`

15 size changes

Type	Base (`933ba9d`)	Merge (`8d4a221`)	Diff
firestore (CSI Auto Indexing Disable and Delete)	272 kB	274 kB	+1.95 kB (+0.7%)
firestore (CSI Auto Indexing Enable)	272 kB	274 kB	+1.95 kB (+0.7%)
firestore (Persistence)	304 kB	306 kB	+2.18 kB (+0.7%)
firestore (Query Cursors)	250 kB	251 kB	+1.31 kB (+0.5%)
firestore (Query)	248 kB	249 kB	+1.31 kB (+0.5%)
firestore (Read data once)	236 kB	237 kB	+1.28 kB (+0.5%)
firestore (Read Write w Persistence)	328 kB	330 kB	+2.24 kB (+0.7%)
firestore (Realtime updates)	238 kB	239 kB	+1.30 kB (+0.5%)
firestore (Transaction)	215 kB	216 kB	+1.25 kB (+0.6%)
firestore (Write data)	214 kB	216 kB	+1.20 kB (+0.6%)
firestore-lite (Query Cursors)	104 kB	104 kB	+702 B (+0.7%)
firestore-lite (Query)	99.9 kB	101 kB	+702 B (+0.7%)
firestore-lite (Read data once)	75.4 kB	75.9 kB	+543 B (+0.7%)
firestore-lite (Transaction)	101 kB	101 kB	+786 B (+0.8%)
firestore-lite (Write data)	85.0 kB	85.5 kB	+572 B (+0.7%)

`firebase`

Type	Base (`933ba9d`)	Merge (`8d4a221`)	Diff
firebase-compat.js	794 kB	797 kB	+2.42 kB (+0.3%)
firebase-data-connect.js	17.6 kB	17.9 kB	+358 B (+2.0%)
firebase-firestore-compat.js	340 kB	342 kB	+2.43 kB (+0.7%)
firebase-firestore-lite.js	131 kB	132 kB	+984 B (+0.7%)
firebase-firestore.js	440 kB	443 kB	+2.42 kB (+0.5%)

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/moJiZXEFA3.html

dconeybe · 2024-06-12T19:25:47Z

IMO adding 2.4 kB to the bundle size is questionable if it's worth it.

google-oss-bot · 2024-06-12T19:35:19Z

Size Analysis Report ¹

This report is too large (723,339 characters) to be displayed here in a GitHub comment. Please use the below link to see the full report on Google Cloud Storage.

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/jHq10E6LcE.html

MarkDuckworth · 2024-06-12T19:35:49Z

IMO adding 2.4 kB to the bundle size is questionable if it's worth it.

@dconeybe, in your opinion, what increase in bundle size would be acceptable?

It's <=1% increase, which seems like a reasonable tradeoff for making production issues more debuggable. But I'm seeing if I can make the impact smaller.

dconeybe · 2024-06-12T20:34:09Z

IMO adding 2.4 kB to the bundle size is questionable if it's worth it.

@dconeybe, in your opinion, what increase in bundle size would be acceptable?

It's <=1% increase, which seems like a reasonable tradeoff for making production issues more debuggable. But I'm seeing if I can make the impact smaller.

I'd hope it would be less than 1kB. But this is just one man's opinion. Please don't take it as gospel truth.

…maller.

…uckworth/error-codes

dconeybe

This is fantastic! I especially like how you added the "context" which will be incredibly useful when debugging. Thanks for doing this, Mark.

dconeybe · 2025-04-02T12:37:35Z

Please let the team know about the 1% increase in code bundle size and make sure they're ok with it. The "firestore (Read Write w Persistence)" bundle increased by 2.77 kB which is probably worth it, but I'd make sure the team knows.

Also, please add a change set with a minor version bump and a change log entry.

hsubox76

Reminder to add a changeset if you want it to publish.

… new and check

dconeybe · 2025-04-03T13:22:49Z

FWIW I much prefer the "hashes" you had before over error codes numerically incrementing from zero. The reason is that hashes have much better "SEO" because of their uniqueness. Firstly, the improved SEO allows customers to search for the error code and find relevant bug reports, stack overflow posts, etc. If they search for error code "3" they won't likely get anything useful, but if they search for "jszxcbe37k" they'll likely get results that relate directly to the error that they are experiencing. Likewise, when we as Firestore SDK developers get a bug report with error code "3" it's much more difficult to find its place in the source code than searching for "jszxcbe37k".

For Data Connect I chose this alphabet: [23456789abcdefghjkmnopqrstuvwxyz](https://github.com/firebase/firebase-android-sdk/blob/a0a02a73f67f6447c739d920f614c8bd5331c591/firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/util/AlphanumericStringUtil.kt#L31C45-L31C79) (a length of 32). This alphabet is most of the English lowercase letters and most digits, with those that "look alike" removed (e.g. zero "0" and lowercase-o "o"). This leads to incredibly unique 6-digit strings.

…value programatically as an error code

…ase-js-sdk into markduckworth/error-codes

dconeybe

Mostly LGTM. Just a few minor comments. Thanks for doing this work! I'll formally "approve" once the comments are addressed/refuted.

.changeset/odd-wolves-sit.md

packages/firestore/scripts/assertion-id-tool.ts

…ase-js-sdk into markduckworth/error-codes

packages/firestore/scripts/build-bundle.ts

packages/firestore/scripts/run-tests.ts

github-actions · 2025-04-11T19:13:46Z

Vertex AI Mock Responses Check ⚠️

A newer major version of the mock responses for Vertex AI unit tests is available. update_vertexai_responses.sh should be updated to clone the latest version of the responses: v10.0

Implement solution to replace error messages with error codes, instea…

53603f3

…d of removing error messages.

MarkDuckworth requested review from a team as code owners June 12, 2024 17:42

Try-catch on saveErrorCode

c7c099a

Replace string errorCodes with numeric errorIds to make the bundles s…

39cf218

…maller.

MarkDuckworth mentioned this pull request Jun 20, 2024

FIRESTORE (10.12.0) INTERNAL ASSERTION FAILED: Unexpected state #8250

Open

MarkDuckworth added 2 commits April 1, 2025 13:40

Merge branch 'main' of github.com:firebase/firebase-js-sdk into markd…

d441861

…uckworth/error-codes

Added fixed error code values to source

448257f

MarkDuckworth assigned dconeybe Apr 1, 2025

dconeybe approved these changes Apr 2, 2025

View reviewed changes

MarkDuckworth added 2 commits April 2, 2025 12:27

Removed 4 characters from each error code

70dcaa7

Deduplicated an error code

a86219b

MarkDuckworth assigned hsubox76 Apr 2, 2025

Fix tests

8b7c3f2

hsubox76 reviewed Apr 2, 2025

View reviewed changes

MarkDuckworth added 2 commits April 2, 2025 18:25

Error codes numerically increasing starting at 0 with tools to create…

26cdf17

… new and check

Instructions for using error-code-tool

8e28999

Create odd-wolves-sit.md

1733442

MarkDuckworth requested a review from a team as a code owner April 3, 2025 13:23

Rename error code to assertion id to deter customers from using this …

3a1eaae

…value programatically as an error code

hsubox76 approved these changes Apr 3, 2025

View reviewed changes

MarkDuckworth added 3 commits April 7, 2025 12:54

Assertion ID back to 4 digit hex

3803a86

Updated assertion id tool to use hex string

fef77fb

Merge branch 'markduckworth/error-codes' of github.com:firebase/fireb…

7416fa2

…ase-js-sdk into markduckworth/error-codes

MarkDuckworth changed the title ~~Implement solution to replace error messages with error codes, instead of removing error messages.~~ Add assertion IDs that will be included in production log statements for fail and hardAsserts Apr 8, 2025

Update odd-wolves-sit.md

70ebdc3

MarkDuckworth requested a review from hsubox76 April 8, 2025 15:33

dconeybe requested changes Apr 8, 2025

View reviewed changes

MarkDuckworth added 3 commits April 8, 2025 17:06

Update odd-wolves-sit.md

d2ef447

Address PR feedback

4374a98

Update prettier to run on scripts/ and commit the results of prettier

a46a147

MarkDuckworth requested a review from dconeybe April 8, 2025 23:46

Merge branch 'markduckworth/error-codes' of github.com:firebase/fireb…

0607d5b

…ase-js-sdk into markduckworth/error-codes

MarkDuckworth commented Apr 8, 2025

View reviewed changes

packages/firestore/scripts/build-bundle.ts Show resolved Hide resolved

MarkDuckworth commented Apr 8, 2025

View reviewed changes

packages/firestore/scripts/run-tests.ts Show resolved Hide resolved

dconeybe approved these changes Apr 9, 2025

View reviewed changes

milaGGL mentioned this pull request Apr 11, 2025

WebChannelConnection RPC 'Listen' stream 0x17d185b2 transport errored #8889

Open

Fix lint error

833f972

MarkDuckworth merged commit e055e90 into main Apr 14, 2025
79 of 100 checks passed

MarkDuckworth deleted the markduckworth/error-codes branch April 14, 2025 16:52

dconeybe mentioned this pull request Apr 14, 2025

failure when logging out: "1 errors occurred during unsubscription:1) Error: FIRESTORE (11.4.0) INTERNAL ASSERTION FAILED: Unexpected state" #8856

Open

google-oss-bot mentioned this pull request Apr 22, 2025

Version Packages #8956

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add assertion IDs that will be included in production log statements for fail and hardAsserts #8313

Add assertion IDs that will be included in production log statements for fail and hardAsserts #8313

MarkDuckworth commented Jun 12, 2024 •

edited

Loading

changeset-bot bot commented Jun 12, 2024 •

edited

Loading

github-actions bot commented Jun 12, 2024 •

edited

Loading

google-oss-bot commented Jun 12, 2024 •

edited

Loading

`@firebase/data-connect`

`@firebase/firestore`

`@firebase/firestore-lite`

`bundle`

`firebase`

dconeybe commented Jun 12, 2024

google-oss-bot commented Jun 12, 2024 •

edited

Loading

MarkDuckworth commented Jun 12, 2024 •

edited

Loading

dconeybe commented Jun 12, 2024

dconeybe left a comment

dconeybe commented Apr 2, 2025

hsubox76 left a comment

dconeybe commented Apr 3, 2025

dconeybe left a comment

github-actions bot commented Apr 11, 2025

Add assertion IDs that will be included in production log statements for fail and hardAsserts #8313

Add assertion IDs that will be included in production log statements for fail and hardAsserts #8313

Conversation

MarkDuckworth commented Jun 12, 2024 • edited Loading

changeset-bot bot commented Jun 12, 2024 • edited Loading

🦋 Changeset detected

github-actions bot commented Jun 12, 2024 • edited Loading

Changeset File Check ✅

google-oss-bot commented Jun 12, 2024 • edited Loading

Size Report 1

Affected Products

@firebase/data-connect

@firebase/firestore

@firebase/firestore-lite

bundle

firebase

Test Logs

dconeybe commented Jun 12, 2024

google-oss-bot commented Jun 12, 2024 • edited Loading

Size Analysis Report 1

Test Logs

MarkDuckworth commented Jun 12, 2024 • edited Loading

dconeybe commented Jun 12, 2024

dconeybe left a comment

Choose a reason for hiding this comment

dconeybe commented Apr 2, 2025

hsubox76 left a comment

Choose a reason for hiding this comment

dconeybe commented Apr 3, 2025

dconeybe left a comment

Choose a reason for hiding this comment

github-actions bot commented Apr 11, 2025

Vertex AI Mock Responses Check ⚠️

MarkDuckworth commented Jun 12, 2024 •

edited

Loading

changeset-bot bot commented Jun 12, 2024 •

edited

Loading

github-actions bot commented Jun 12, 2024 •

edited

Loading

google-oss-bot commented Jun 12, 2024 •

edited

Loading

Size Report ¹

`@firebase/data-connect`

`@firebase/firestore`

`@firebase/firestore-lite`

`bundle`

`firebase`

google-oss-bot commented Jun 12, 2024 •

edited

Loading

Size Analysis Report ¹

MarkDuckworth commented Jun 12, 2024 •

edited

Loading