Carregar arquivos dSYM

O Xcode armazena os arquivos dSYM do seu aplicativo na pasta do caminho de arquivamento dSYM. Esta é a pasta onde o agente do iOS obtém os arquivos dSYM que ele usa para simbolizar seus relatórios de falhas. A New Relic fornece um script pós-compilação como parte do processo de instalação do agente do iOS. Este script converte automaticamente seu dSYM para o formato de arquivo de mapa da New Relic e faz o upload dos arquivos necessários para a simbolização de falhas para a New Relic.

Script automático

O agente iOS inclui run-symbol-tool, um script de shell que você executa a partir de uma fase de compilação Run Script no Xcode. Após cada compilação, ele executa run-symbol-tool.swift em segundo plano, o que converte seus arquivos dSYM para o formato de arquivo de mapa do New Relic e os envia para o New Relic.

No Xcode 14, a Apple alterou a configuração padrão em projetos recém-criados para desabilitar o bitcode. A App Store agora só aceita envios de aplicativos com bitcode desativado. Consulte as notas de versão do Xcode 14. Se o seu projeto ainda tiver o bitcode habilitado você deverá desabilitá-lo. O script automático requer que o bitcode esteja desabilitado.

A Apple gera arquivos dSYM para aplicativos habilitados para Bitcode. Você deve baixar os arquivos dSYM para aplicativos habilitados para Bitcode da Apple e carregá-los no New Relic por meio do monitoramento de Mobile UI.

Se você vir um código de máquina ilegível na páginaCrashes , seus arquivos dSYM podem não ter sido carregados corretamente. Em alguns casos, pode ser necessário fazer upload manual de arquivos dSYM.

Importante

Agente iOS versão 7.4.8 removidos os scripts de upload do Python (generateMap.py, generateMapPython2.py e newrelic_postbuild.sh). Se a sua fase de compilação Run Script ainda chamar newrelic_postbuild.sh, substitua-a pelo script run-symbol-tool abaixo.

Adicione a fase de compilação Run script

No Xcode, selecione seu projeto no navegador e, em seguida, selecione o destino do seu aplicativo.
Selecione a guia Build Phases .
Clique em + e escolha New Run Script Phase.
Adicione as seguintes linhas à nova fase. Substitua APP_TOKEN pelo token do seu aplicativo do New Relic.
bash
```
$ARTIFACT_DIR="${BUILD_DIR%Build/*}"
$SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
$/bin/sh "${SCRIPT}" "APP_TOKEN"
```

No Xcode 15.3 ou superior, é necessário definir User Script Sandboxing como No para que o script possa ler seus arquivos dSYM e gravar seu log. Consulte Falhas no upload automático de dSYM.

Argumentos opcionais

Adicione argumentos opcionais após o token do aplicativo, em qualquer ordem:

Argumento	Descrição
`--debug`	Grava detalhes adicionais em `upload_dsym_results.log`, como os caminhos de dSYM, a URL de upload e os comandos de upload. A saída de depuração inclui o token do seu aplicativo.
`-appVersion <version>`	Define a versão do aplicativo que é reportada com os símbolos enviados. O script também aceita `--appVersion` e `--app-version`. Requer o agente iOS versão 7.7.5 ou superior. Consulte Versão do aplicativo.

Por exemplo:

bash

$ARTIFACT_DIR="${BUILD_DIR%Build/*}"
$SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
$/bin/sh "${SCRIPT}" "APP_TOKEN" -appVersion "1.4.2" --debug

Versão do aplicativo

O New Relic associa os símbolos enviados às suas builds pela versão do aplicativo. O script usa o primeiro valor não vazio desta lista:

O argumento -appVersion
A variável de ambiente NEWRELIC_APP_VERSION
A configuração de build MARKETING_VERSION
O espaço reservado 1.2.3

Quando o script usa o espaço reservado, ele registra um aviso em upload_dsym_results.log.

Alguns projetos não definem MARKETING_VERSION, como aplicativos versionados com agvtool ou aplicativos de vários destinos que usam GENERATE_INFOPLIST_FILE = YES. Para esses projetos, passe -appVersion ou defina NEWRELIC_APP_VERSION para que seus símbolos correspondam às suas compilações.

Variáveis ambientais

Você não precisa definir essas variáveis para um upload padrão. Para definir uma, adicione uma linha export acima do script na mesma fase Run Script:

bash

$export NEWRELIC_APP_VERSION="1.4.2"
$ARTIFACT_DIR="${BUILD_DIR%Build/*}"
$SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
$/bin/sh "${SCRIPT}" "APP_TOKEN"

O script suporta estas variáveis de ambiente:

Variável	Descrição
`NEWRELIC_APP_VERSION`	Versão do aplicativo relatada com os símbolos enviados. Requer agente iOS versão 7.7.5 ou superior. Consulte a Versão do aplicativo.
`DSYM_UPLOAD_URL`	Host de upload. O padrão é `https://mobile-symbol-upload.newrelic.com`. O script ignora essa variável quando o token do seu aplicativo tem um prefixo de região, como tokens EU ou JP. Esses tokens sempre usam seu host regional.
`NEWRELIC_SYMBOL_ENDPOINT`	Caminho para uploads de arquivos de mapa. O padrão é `map`.
`NEWRELIC_DSYM_ENDPOINT`	Caminho para uploads de dSYM. O padrão é `symbol`.
`NEWRELIC_SYMBOL_POST_KEY`	Nome do campo do formulário para uploads de arquivo de mapa. O padrão é `upload`.
`NEWRELIC_DSYM_POST_KEY`	Nome do campo de formulário para uploads de dSYM. O padrão é `dsym`.

Como o script funciona

Quando executado, o script faz o seguinte:

O upload é executado em segundo plano, por isso seu build não espera que ele termine. O script grava os resultados em upload_dsym_results.log.
O script ignora as compilações do simulador do iOS (EFFECTIVE_PLATFORM_NAME é -iphonesimulator).
Builds com bitcode habilitado (ENABLE_BITCODE = YES) encerram sem realizar o upload e sem causar falha no build.
O script converte cada dSYM em DWARF_DSYM_FOLDER_PATH em um arquivo de mapa, compacta os arquivos de mapa e faz o upload do zip para o endpoint /map.
Se um dSYM não puder ser convertido, o script compacta esse dSYM e faz o upload dele para o endpoint /symbol em vez disso. Se o próprio upload do mapa falhar, o script registra o código de status HTTP e não recorre a um upload de dSYM. Nesse caso, faça o upload do dSYM manualmente.
Na versão 7.7.2 e superior do agente iOS, se um arquivo de mapa compactado for maior que 200 MB, o script não faz o upload dele. Ele envia apenas o tamanho do arquivo e a versão do aplicativo para o New Relic. O New Relic não pode simbolizar falhas dessa compilação, a menos que você faça o upload do seu dSYM manualmente.
O script escolhe a região de upload (US, EU ou JP) a partir do token do seu aplicativo. Estes são os mesmos hosts usados nos comandos de upload manual.

Identifique dSYMs ausentes

Quando um aplicativo com Bitcode ativado é enviado para a Apple para análise da App Store ou distribuição ad-hoc, os dSYMs precisam ser baixados manualmente da Apple e enviados para a New Relic para permitir que os relatórios de falhas de dispositivos móveis sejam devidamente simbolizados. Esses dSYMs podem ser baixados por meio do organizador de arquivos no Xcode alguns minutos após o upload do aplicativo. Nesta situação, siga os procedimentos para encontrar o arquivo e baixar os dSYMs.

Se um aplicativo não tiver um arquivo dSYM, você verá três indicadores na interface de monitoramento do Mobile:

Banner notification: um banner de aviso aparece na páginaCrash report . O aviso diz:

We were unable to locate your dsym.

Upload prompt: na página Crash type summary você será automaticamente solicitado a fazer upload de um arquivo dSYM se ele estiver faltando.
Machine code: o stack trace de falhas na página Crash report exibe código de máquina e não uma mensagem de erro legível.

Upload de arquivos dSYM através da interface de monitoramento de Mobile

Você pode facilmente fazer o upload dos seus arquivos dSYM diretamente da interface do New Relic. Para limites de tamanho, consulte Limitações. Para fazer o upload dos seus arquivos dSYM:

Vá para one.newrelic.com > All capabilities > Mobile. Em seguida, selecione seu aplicativo na lista.
Visualizar Crashes.
Selecione uma falha específica do Total crashes em Falhas do grupo.
Clique em Upload dSYM. Você pode arrastar e soltar seus dSYMs diretamente ou selecionar o arquivo em seu computador.

Carregar arquivos dSYM manualmente

Em algumas circunstâncias, o envio automático de arquivos dSYM do New Relic pode falhar. Por exemplo, se houver uma falha de rede e o envio não for concluído, upload_dsym_results.log registra o que deu errado. Para obter informações adicionais sobre como o New Relic lida com envios de dSYM, consulte a Comunidade técnica online do New Relic.

Se o upload automático falhar, você pode fazer o upload manual do seu arquivo dSYM. Se você tiver vários arquivos dSYM, eles podem estar em um único zip. Para limites de tamanho, consulte Limitações. O valor YOUR_NEW_RELIC_APPLICATION_TOKEN nos comandos abaixo é a mesma chave usada para +[NewRelic startWithApplicationToken:] (em Objective-C) ou NewRelic.start(withApplicationToken:) (em Swift).

Nos comandos abaixo, use caminhos completos ou $HOME. O shell não expande ~ dentro de aspas.

Para carregar manualmente seus arquivos dSYM:

Você pode executar run-symbol-tool.swift a partir da linha de comando. Ele converte os arquivos dSYM em uma pasta, como a pasta dSYMs de um arquivo do Xcode, e faz o upload deles da mesma forma que o script automático. O script está na mesma pasta que run-symbol-tool (por exemplo, NewRelic.xcframework/Resources).

bash

$DWARF_DSYM_FOLDER_PATH="DSYM_FOLDER_PATH" /usr/bin/xcrun --sdk macosx swift "SCRIPT_PATH/run-symbol-tool.swift" "YOUR_NEW_RELIC_APPLICATION_TOKEN" -appVersion "APP_VERSION"

Substituir:

DSYM_FOLDER_PATH com o caminho completo para a pasta que contém seus arquivos .dSYM (por exemplo, $HOME/Library/Developer/Xcode/Archives/2026-10-22/MyApp.xcarchive/dSYMs).
SCRIPT_PATH com o caminho completo para a pasta que contém run-symbol-tool.swift.
APP_VERSION com a versão da compilação. MARKETING_VERSION não é definido fora do Xcode, portanto, passe a versão explicitamente. Para versões do agente de 7.4.12 a 7.7.4, defina MARKETING_VERSION="APP_VERSION" antes do comando em vez de passar -appVersion.

O script imprime sua saída no terminal.

Resolução de problemas

O script run-symbol-tool grava upload_dsym_results.log no diretório raiz do seu projeto a cada compilação, independentemente de o upload ser bem-sucedido ou falhar. Cada compilação substitui o log anterior. Para gravar mais detalhes no log, adicione o argumento --debug .

Se o seu log de build mostrar upload_dsym_results.log: Operation not permitted, consulte Falhas no envio automático de dSYM.

DSYMs ausentes

Se os arquivos dSYM estiverem faltando, pode ser necessário verificar as configurações de compilação do Xcode para garantir que o arquivo esteja sendo gerado. frameworks construídos localmente têm configurações de construção separadas e também podem precisar ser atualizados.

Configurações de compilação:

Debug Information Format : Dwarf with dSYM File
Deployment Postprocessing: Yes
Strip Linked Product: Yes
Strip Debug Symbols During Copy : Yes

Limitações

Esteja ciente destes limites de tamanho:

Os uploads de dSYM compactados por meio da interface de monitoramento de móviles ou da linha de comando podem ter até 600 MB.
O script automático não faz upload de arquivos de mapa compactados maiores que 200 MB. Consulte Como o script funciona.

Esta tradução de máquina é fornecida para sua comodidade.

Script automático

Importante

Adicione a fase de compilação Run script

Argumentos opcionais

Versão do aplicativo

Variáveis ambientais

Como o script funciona

Identifique dSYMs ausentes

Upload de arquivos dSYM através da interface de monitoramento de Mobile

Carregar arquivos dSYM manualmente

Via script Swift

Resolução de problemas

DSYMs ausentes

Limitações

Esta tradução de máquina é fornecida para sua comodidade.

Carregar arquivos dSYM

Script automático .css-21sua1{background:none;border:none;width:0;padding:0;}

Importante

Adicione a fase de compilação Run script

Argumentos opcionais

Versão do aplicativo

Variáveis ambientais

Como o script funciona

Identifique dSYMs ausentes

Upload de arquivos dSYM através da interface de monitoramento de Mobile

Carregar arquivos dSYM manualmente

Resolução de problemas

DSYMs ausentes

Limitações

Script automático