/symbol-collector

Clients and Server to collect system symbols.

Primary LanguageC#MIT LicenseMIT


Symbol Collector

build codecov Discord Chat

Collect system symbols from different devices like Android, macOS, Linux, etc. It involves a server that writes the symbols to Google cloud storage and a set of clients.

Symbol Collector on a device farm

Uploading symbols

Client applications

Current clients are:

  • Android
  • macOS
  • Linux

The client applications will parse files and make sure they are valid ELF, Mach-O, Fat Binary, etc. Besides that, before uploading it to the server, it will make a HEAD request with the image build id to make sure this file is still missing, to avoid wasting time and bandwidth uploading redundant files.

Looking for system images in the filesystem and the HTTP requests happen in parallel, so to go through GBs and thousands of files takes only a few seconds. Finally, the client apps will upload its internal metrics to help reconcile the batch results and troubleshoot any issues.

cURL

Although using the client programs is strongly recommended, it's possible to upload files via HTTP.

For example, uploading a batch of Android symbols:

  1. Create a batch:
export batchId=$(uuidgen)
export batchFriendlyName="Android 4.4.4 - Sony Xperia"
export batchType="Android"
export body='{"BatchFriendlyName":"'$batchFriendlyName'","BatchType":"'$batchType'"}'
export server=http://localhost:5000

curl -sD - --header "Content-Type: application/json" --request POST \
  --data "$body" \
  $server/symbol/batch/$batchId/start
  1. Upload files:
curl -i \
  -F "libxamarin-app-arm64-v8a.so=@test/TestFiles/libxamarin-app-arm64-v8a.so" \
  -F "libxamarin-app.so=@test/TestFiles/libxamarin-app.so" \
  $server/symbol/batch/$batchId/upload
  1. Close batch (without providing metrics):
curl -sD - --header "Content-Type: application/json" --request POST \
  --data "{}" \
  $server/symbol/batch/$batchId/close

Why are you doing this?

In order to stack unwind from a memory dump, every loaded image involved in the call stack needs to be available. Unwind information is not in the debug files but in the libraries instead. This project allows collecting these libraries so that native crash processing can be done on the backend as opposed to stackwalking on the client.

Releases

The Releases page in this repository include builds for Android (apk), native CLIs for macOS and Linux (self contained), and the server.

Building from source

Dependencies

This project includes an Android app, an ASP.NET Core server and a Console apps as CLI clients for macOS and Linux. The build script build.sh is focused on building all the components which means you'd need all the dependencies below.

Server and Console app

To build the Server, Libraries and the Console app (aka: everything except the Android app) you'll need:

Android app

To build the Android project you need:

  • JDK 11
  • .NET Android workload: dotnet workload install android

Resources