sp_trace_create (Transact-SQL)

Aplica-se a: simSQL Server (todas as versões compatíveis)

Cria uma definição de rastreamento. O rastreamento novo estará em um estado interrompido.

Importante

Esse recurso será removido em uma versão futura do Microsoft SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam. Em vez disso, use Eventos Estendidos.

Ícone de link do tópico Convenções da sintaxe Transact-SQL

Sintaxe

  
sp_trace_create [ @traceid = ] trace_id OUTPUT   
          , [ @options = ] option_value   
          , [ @tracefile = ] 'trace_file'   
     [ , [ @maxfilesize = ] max_file_size ]  
     [ , [ @stoptime = ] 'stop_time' ]  
     [ , [ @filecount = ] 'max_rollover_files' ]  

Argumentos

[ @traceid = ] trace_id É o número atribuído por Microsoft SQL Server ao novo rastreamento. Qualquer entrada fornecida pelo usuário será ignorada. trace_id é int, com um padrão null. O usuário emprega o valor trace_id para identificar, modificar e controlar o rastreamento definido por este procedimento armazenado.

[ @options = ] option_value Especifica as opções definidas para o rastreamento. option_value é int, sem padrão. Os usuários podem escolher uma combinação destas opções especificando o valor de soma das opções escolhidas. Por exemplo, para ativar as duas opções TRACE_FILE_ROLLOVER e SHUTDOWN_ON_ERROR, especifique 6 para option_value.

A tabela a seguir lista as opções, as descrições e seus valores.

Nome da opção Valor de opção Descrição
TRACE_FILE_ROLLOVER 2 Especifica que, quando o max_file_size é atingido, o arquivo de rastreamento atual é fechado e um novo arquivo é criado. Todos os novos registros serão gravados no novo arquivo. O novo arquivo terá o mesmo nome do anterior, mas um número inteiro será adicionado para indicar a sequência. Por exemplo, se o arquivo de rastreamento original for filename.trc, o próximo arquivo de rastreamento será filename_1.trc, o seguinte será filename_2.trc, e assim por diante.

Quanto mais arquivos de rastreamento de substituição forem criados, o valor do inteiro adicionado ao nome de arquivo aumentará consecutivamente.

SQL Server usa o valor padrão de max_file_size (5 MB) se essa opção for especificada sem especificar um valor para max_file_size .
SHUTDOWN_ON_ERROR 4 Especifica que, se o rastreamento não puder ser gravado no arquivo por qualquer motivo, o SQL Server será encerrado. Esta opção é útil ao executar rastreamentos de auditoria de segurança.
TRACE_PRODUCE_BLACKBOX 8 Especifica que um registro dos últimos 5 MB de informações de rastreamento produzidas pelo servidor será salvo pelo servidor. TRACE_PRODUCE_BLACKBOX é incompatível com todas as outras opções.

[ @tracefile = ] 'trace_file' Especifica o local e o nome do arquivo no qual o rastreamento será gravado. trace_file é nvarchar(245) sem padrão. trace_file pode ser um diretório local (como N 'C:\MSSQL\Trace\trace.trc') ou um UNC para um compartilhamento ou caminho (N' \ \ Nome do \ servidorNome do Sharename \ Directory\trace.trc').

SQL Server anexa uma extensão .trc a todos os nomes de arquivo de rastreamento. Se a TRACE_FILE_ROLLOVER e um max_file_size for especificado, o criará um novo arquivo de rastreamento quando o arquivo de rastreamento original crescer SQL Server para seu tamanho máximo. O novo arquivo tem o mesmo nome que o arquivo original, mas _ n é anexado para indicar sua sequência, começando com 1. Por exemplo, se o primeiro arquivo de rastreamento for chamado filename.trc, o segundo arquivo de rastreamento será chamado filename_1.trc.

Se você usa a opção TRACE_FILE_ROLLOVER, é recomendável que não use caracteres de sublinhado no nome de arquivo de rastreamento original. Se você usar sublinhados, ocorrerá o seguinte comportamento:

  • SQL Server Profiler não carrega automaticamente nem solicita que você carregue os arquivos de sobrecarrização (se qualquer uma dessas opções de sobreover de arquivo estiver configurada).

  • A fn_trace_gettable não carrega arquivos de sobressalto (quando especificado usando o argumento number_files) em que o nome do arquivo original termina com um sublinhado e um valor numérico. (Isso não se aplica ao sublinhado e ao número que são acrescentados automaticamente quando um arquivo é substituído.)

Observação

Como alternativa para ambos os comportamentos, você pode renomear os arquivos de rastreamento para remover os sublinhados no nome de arquivo original. Por exemplo, se o arquivo original for chamado my_trace.trc e o arquivo de sobressaixamento for chamado my_trace_1.trc, você poderá renomear os arquivos para mytrace.trc e mytrace_1.trc antes de abrir os arquivos no SQL Server Profiler .

trace_file não pode ser especificado quando a TRACE_PRODUCE_BLACKBOX é usada.

[ @maxfilesize = ] max_file_size Especifica o tamanho máximo em megabytes (MB) que um arquivo de rastreamento pode crescer. max_file_size é bigint, com um valor padrão de 5.

Se esse parâmetro for especificado sem a opção TRACE_FILE_ROLLOVER, o rastreamento para de gravar no arquivo quando o espaço em disco usado exceder a quantidade especificada por max_file_size.

[ @stoptime = ] 'stop_time' Especifica a data e a hora em que o rastreamento será interrompido. stop_time é datetime, com um padrão null. Se for NULL, o rastreamento será executado até que seja parado manualmente ou até que o servidor seja encerrado.

Se stop_time e max_file_size for especificado e TRACE_FILE_ROLLOVER não for especificado, o rastreamento será superior quando o tempo de parada especificado ou o tamanho máximo do arquivo for atingido. Se stop_time, max_file_size e TRACE_FILE_ROLLOVER for especificado, o rastreamento será interrompido no horário de parada especificado, supondo que o rastreamento não preencha a unidade.

[ @filecount = ] 'max_rollover_files' Especifica o número máximo ou os arquivos de rastreamento a serem mantidos com o mesmo nome de arquivo base. max_rollover_files é int, maior que um. Este parâmetro só será válido se a opção TRACE_FILE_ROLLOVER for especificada. Quando max_rollover_files é especificado, tenta manter não mais do que max_rollover_files de rastreamento excluindo o arquivo de rastreamento mais antigo antes de abrir um novo arquivo SQL Server de rastreamento. O SQL Server rastreia a idade dos arquivos de rastreamento adicionando um número ao nome de arquivo base.

Por exemplo, quando o parâmetro trace_file é especificado como "c:\mytrace", um arquivo com o nome "c:\mytrace_123.trc" é mais antigo do que um arquivo com o nome "c:\mytrace_124.trc". Se max_rollover_files estiver definido como 2, SQL Server excluirá o arquivo "c:\mytrace_123.trc" antes de criar o arquivo de rastreamento "c:\mytrace_125.trc".

Observe que o SQL Server tenta excluir cada arquivo somente uma vez e não pode excluir um arquivo que está sendo usado por outro processo. Portanto, se outro aplicativo estiver trabalhando com arquivos de rastreamento enquanto o rastreamento está em execução, o SQL Server poderá deixar esses arquivos de rastreamento no sistema de arquivos.

Valores do código de retorno

A tabela a seguir descreve os valores de código que os usuários podem obter após a conclusão do procedimento armazenado.

Código de retorno Descrição
0 Nenhum erro.
1 Erro desconhecido.
10 Opções inválidas. Retornado quando as opções especificadas são incompatíveis.
12 Arquivo não criado.
13 Sem memória. Retornado quando não há memória suficiente para executar a ação especificada.
14 Horário de parada inválido. Retornado quando o horário de parada especificado já aconteceu.
15 Parâmetros inválidos. Retornado quando o usuário forneceu parâmetros incompatíveis.

Comentários

sp_trace_create é um procedimento armazenado que executa muitas das ações executadas anteriormente SQL Server pelo xp_trace_ _ procedimentos armazenados estendidos disponíveis em versões anteriores do * SQL Server. Use _ sp_trace_create em vez de:

  • xp_trace_addnewqueue

  • xp_trace_setqueuecreateinfo

  • xp_trace_setqueuedestination

sp_trace_create cria apenas uma definição de rastreamento. Este procedimento armazenado não pode ser usado para iniciar ou alterar um rastreamento.

Parâmetros de todos os SQL procedimentos armazenados de rastreamento (sp_trace_xx) são estritamente digitados. Se esses parâmetros não forem chamados com os tipos de dados com parâmetro de entrada corretos, como especificado na descrição do argumento, o procedimento armazenado retornará um erro.

Por sp_trace_create, a SQL Server conta de serviço deve ter permissão de gravação na pasta de arquivos de rastreamento. Se a conta de serviço do SQL Server não for um administrador no computador onde o arquivo de rastreamento está localizado, você deve conceder explicitamente a permissão de gravação para a conta de serviço do SQL Server.

Observação

Você pode carregar automaticamente o arquivo de rastreamento criado com sp_trace_create em uma tabela usando a função de sistema fn_trace_gettable . para obter informações sobre como usar essa função do sistema, consulte sys.fn_trace_gettable (Transact-SQL).

Para obter um exemplo de como usar procedimentos armazenados de rastreamento, veja Criar um rastreamento (Transact-SQL).

TRACE_PRODUCE_BLACKBOX tem as seguintes características:

  • É um rastreamento de substituição. O file_count padrão é 2, mas pode ser substituído pelo usuário usando a opção FileCount .

  • O file_size padrão como com outros rastreamentos é de 5 MB e pode ser alterado.

  • Nenhum nome de arquivo pode ser especificado. O arquivo será salvo como: N '%SQLDIR%\MSSQL\DATA\blackbox.trc '

  • Apenas os eventos a seguir e suas colunas são contidas no rastreamento:

    • RPC starting

    • Batch starting

    • Exceção

    • Attention

  • Eventos ou colunas não podem ser adicionados ou removidos desse rastreamento.

  • Não é possível especificar filtros para este rastreamento.

Permissões

O usuário deve ter a permissão ALTER TRACE.

Consulte Também

sp_trace_generateevent (Transact-SQL)
sp_trace_setevent (Transact-SQL)
sp_trace_setfilter (Transact-SQL)
sp_trace_setstatus (Transact-SQL)
Rastreamento do SQL