Partilhar via

  • Artigo

sp_trace_create (Transact-SQL)

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

Ícone de vínculo de tópicoConvenções de 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 pelo MicrosoftSQL Server ao novo rastreamento. Qualquer entrada fornecida pelo usuário será ignorada. trace_id é int, com o 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 o conjunto de opções para o rastreamento. option_value é int, sem nenhum 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 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 da opção

    Descrição

    TRACE_FILE_ROLLOVER

    2

    Especifica que, quando o max_file_size for atingido, o arquivo de rastreamento atual será fechado e um novo arquivo será 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 seqüê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.

    O SQL Server usa o valor padrão de max_file_size (5 MB) se essa opção for especificada sem a especificação de 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 de arquivo no qual o rastreamento será gravado. trace_file é nvarchar(245) sem nenhum padrão. trace_file pode ser um diretório local (como N 'C:\MSSQL\Trace\trace.trc') ou um UNC até um compartimento ou caminho (N'\\Servername\Sharename\Directory\trace.trc').

    O SQL Server adicionará uma extensão .trc a todos os nomes de arquivo de rastreamento. Se a opção TRACE_FILE_ROLLOVER e um max_file_size forem especificados, o SQL Server criará um novo arquivo de rastreamento quando o arquivo de rastreamento original atingir o tamanho máximo. O novo arquivo tem o mesmo nome do original, mas _n é adicionado para indicar a seqüência, começando com 1. Por exemplo, se o primeiro arquivo de rastreamento for filename.trc, o segundo arquivo de rastreamento será 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:

    • O SQL Server Profiler não será carregado automaticamente ou você será solicitado a carregar os arquivos de substituição (se qualquer uma dessas opções de substituição de arquivo estiver configurada).

    • A função fn_trace_gettable não carregará arquivos de substituição (quando especificada com o argumento number_files) onde o nome de arquivo de rastreamento original terminar 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çãoObservaçã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 tiver o nome my_trace.trc e o arquivo de substituição tiver o nome my_trace_1.trc, você poderá renomear os arquivos para mytrace.trc e mytrace_1.trc antes de abri-los no SQL Server Profiler.

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

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

    Se esse parâmetro for especificado sem a opção TRACE_FILE_ROLLOVER, o rastreamento deixará de ser registrado no arquivo quando o espaço em disco ultrapassar o valor especificado por max_file_size.

  • [ @stoptime= ] 'stop_time'
    Especifica a data e a hora em que o rastreamento será interrompido. stop_time é datetime, com o 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 forem especificados, mas TRACE_FILE_ROLLOVER não for especificado, o rastreamento será interrompido quando o tempo limite ou o tamanho de arquivo máximo especificado for atingido. Se stop_time, max_file_size e TRACE_FILE_ROLLOVER forem especificados, o rastreamento será interrompido no tempo limite especificado, supondo que o rastreamento não encherá 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 do que um. Este parâmetro só será válido se a opção TRACE_FILE_ROLLOVER for especificada. Quando max_rollover_files é especificado, o SQL Server tenta manter não mais do que max_rollover_files arquivos de rastreamento excluindo o arquivo de rastreamento mais antigo antes de abrir um novo arquivo. 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 for definido como 2, o 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 de 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

Memória insuficiente. 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 do SQL Server que executa muitas das ações anteriormente executadas por procedimentos armazenados estendidos xp_trace_* 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 só cria uma definição de rastreamento. Este procedimento armazenado não pode ser usado para iniciar ou alterar um rastreamento.

Os parâmetros de todos os procedimentos armazenados do Rastreamento SQL (sp_trace_xx) são rigorosamente tipados. 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.

Para sp_trace_create, a conta de serviço do SQL Server 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çãoObservação

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

Para obter um exemplo do uso de procedimentos armazenados de rastreamento, consulte Como criar um rastreamento (Transact-SQL).

TRACE_PRODUCE_BLACKBOX tem as características seguintes:

  • É 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 em outros rastreamentos, é 5 MB e pode ser alterado.

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

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

    • RPC starting

    • Batch starting

    • Exception

    • 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.

Histórico de alterações

Conteúdo atualizado

Adicionada a recomendação para evitar o uso de caracteres de sublinhado no nome de arquivo de rastreamento original à descrição do argumento @tracefile.