Register debug symbols

The ffx debug symbol-index commands help manage Fuchsia components’ debug symbols in your development environment.

Concepts

During development, debug symbols for a Fuchsia component are generated as part of build artifacts. A file containing debug symbols has .symbol-index.json as a postfix (for example, my-component.symbol-index.json).

Registering a Fuchsia component's debug symbols in your development environment enables the following workflows:

  • View the component's logs in symbolized format.
  • Use the Fuchsia debugger to step through the code while the component is running on a device.
  • Monitor the component's FIDL traffic on a device in real time.

In addition to registering locally generated debug symbols, you can also configure your environment to retrieve debug symbols from an online storage (for instance, Google Cloud Storage). Once an online storage is added in your global symbol-index configuration, various Fuchsia debugging tools (such as ffx log and ffx debug connect) can automatically download and use the debug symbols available in the online storage.

In a Fuchsia development environment, a registration of debug symbols often takes place in the background. Some Fuchsia tools are configured to invoke the registration of debug symbols (using ffx debug symbol-index add) upon detection of debug symbols, so you may never need to manually register the debug symbols of your Fuchsia component during development. For instance, if you're using Fuchsia's Bazel rules, the debug symbols get registered automatically as part of the build. However, when necessary, you could use the ffx debug symbol-index commands to manage debug symbols directly.

List registered debug symbols

To view your global symbol-index configuration, run the following command:

ffx debug symbol-index list

This command prints output similar to the following:

$ ffx debug symbol-index list
SymbolIndex {
    includes: [
        "/usr/alice/home/my-fuchsia-project/my-component.symbol-index.json",
    ],
    build_id_dirs: [],
    ids_txts: [],
    gcs_flat: [
        GcsFlat {
           url: "gs://our-fuchsia-project/debug",
           require_authentication: false,
        },
    ],
    debuginfod: []
}

Add a debuginfod symbol server

When working with third party binaries that are not built in the Fuchsia tree, you may be able to add a debuginfod server to fetch the symbols. Upstream distributions provide debuginfod servers, such as debuginfod.debian.net or "federated" servers, such as debuginfod.elfutils.org which will serve symbols from many different upstream sources. Check with your upstream source to find their debuginfod server, if they offer one. Often, these will be presented as environment variables, such as this:

export DEBUGINFOD_URLS="https://debuginfod.debian.net

To add a debuginfod server such as above to your symbol-index, use the following command:

ffx debug symbol-index add <URL>

Replace URL with the URL for the debuginfod server you would like to add. For example, to add Debian's debuginfod server, run the following command:

ffx debug symbol-index add https://debuginfod.debian.net

When the registration is successful, the command exits silently without output. Debugging tools will automatically query the server for symbols that cannot be found locally.

If you want to verify the registration, see List registered debug symbols.

Remove a debuginfod symbol server

To remove a debuginfod server from your global symbol-index configuration, run the following command:

ffx debug symbol-index remove <URL>

Replace URL with the URL for the debuginfod server you would like to remove. The example below removes the debian debuginfod server:

ffx debug symbol-index remove https://debuginfod.debian.net

Manually register local debug symbols

To register debug symbols in your environment, run the following command:

ffx debug symbol-index add <PATH_TO_DEBUG_SYMBOLS>

Replace PATH_TO_DEBUG_SYMBOLS with an absolute path to a debug symbols file.

The example below registers the debug symbols of the my-component component:

$ ffx debug symbol-index add /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json

When the registration is successful, the command exits silently without output.

If you want to verify the registration, see List registered debug symbols.

Remove registered local debug symbols

To remove debug symbols from your global symbol-index configuration, run the following command:

ffx debug symbol-index remove <PATH_TO_DEBUG_SYMBOLS>

Replace PATH_TO_DEBUG_SYMBOLS with the exact path to a registered debug symbols file to be removed.

The example below removes the debug symbols of the my-component component:

$ ffx debug symbol-index remove /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json

When the removal is successful, the command exits silently without output.

Clean up misplaced debug symbols

Deleting a registered debug symbols file on the host machine does not mean that your global symbol-index configuration also gets updated automatically.

To remove any stale paths (pointing to deleted debug symbols files) from the global symbol-index configuration, run the following command:

ffx debug symbol-index clean

For instance, if the /usr/alice/home/my-fuchsia-project directory no longer exists on the host machine, this command removes the /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json entry from the global symbol-index configuration.