sp_trace_create (Transact-SQL)

  • Artigo

Aplica-se: SQL Server

Cria uma definição de rastreamento. O novo rastreamento está em um estado parado.

Importante

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

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_trace_create
    [ @traceid = ] traceid OUTPUT
    , [ @options = ] options
    , [ @tracefile = ] N'tracefile'
    [ , [ @maxfilesize = ] maxfilesize ]
    [ , [ @stoptime = ] 'stoptime' ]
    [ , [ @filecount = ] filecount ]
[ ; ]

Argumentos

@traceid [ = ] traceid SAÍDA

O número atribuído pelo SQL Server ao novo rastreamento. Qualquer entrada fornecida pelo usuário é ignorada. @traceid é um parâmetro OUTPUT do tipo int, com um padrão de NULL. O usuário emprega o valor @traceid para identificar, modificar e controlar o rastreamento definido por esse procedimento armazenado.

@options [ = ] opções

Especifica as opções definida para o rastreamento. @options é int, sem padrão. Você pode escolher uma combinação dessas opções especificando o valor da soma das opções escolhidas. Por exemplo, para ativar as opções TRACE_FILE_ROLLOVER e SHUTDOWN_ON_ERROR, especifique 6 para @options.

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 @filecount é atingido, o arquivo de rastreamento atual é fechado e um novo arquivo é criado. Todos os novos registros são gravados no novo arquivo. O novo arquivo tem o mesmo nome que o arquivo anterior, mas um número inteiro é anexado para indicar sua sequência. Por exemplo, se o arquivo de rastreamento original for nomeado filename.trc, o próximo arquivo de rastreamento será nomeado filename_1.trc, o arquivo de rastreamento a seguir 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 usará o valor padrão de @filecount (5 MB) se essa opção for especificada sem especificar um valor para @filecount.
SHUTDOWN_ON_ERROR 4 Especifica que, se o rastreamento não puder ser gravado no arquivo por qualquer motivo, o SQL Server será desligado. 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 é salvo pelo servidor. TRACE_PRODUCE_BLACKBOX é incompatível com todas as outras opções.

@tracefile [ = ] N'tracefile'

Especifica o local e o nome do arquivo no qual o rastreamento é gravado. @tracefile é nvarchar(245) sem padrão. @tracefile pode ser um diretório local (como N'C:\MSSQL\Trace\trace.trc') ou um UNC para um compartilhamento ou caminho (como N'\\<servername>\<sharename>\<directory>\trace.trc').

O SQL Server acrescenta uma .trc extensão a todos os nomes de arquivo de rastreamento. Se a TRACE_FILE_ROLLOVER opção e um @filecount forem especificados, o SQL Server criará um novo arquivo de rastreamento quando o arquivo de rastreamento original crescer até seu tamanho máximo. O novo arquivo tem o mesmo nome do arquivo original, mas _n é anexado para indicar sua sequência, começando com 1. Por exemplo, se o primeiro arquivo de rastreamento for denominado filename.trc, o segundo arquivo de rastreamento será denominado filename_1.trc.

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

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

  • A função sys.fn_trace_gettable não carrega arquivos de substituição (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 anexados 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 nomeado my_trace.trce o arquivo de substituição for nomeado my_trace_1.trc, você poderá renomear os arquivos para mytrace.trc e mytrace_1.trc antes de abri-los no SQL Server Profiler.

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

@maxfilesize [ = ] maxfilesize

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

Se esse parâmetro for especificado sem a TRACE_FILE_ROLLOVER opção, o rastreamento interromperá a gravação no arquivo quando o espaço em disco usado exceder a quantidade especificada por @maxfilesize.

@stoptime [ = ] 'tempo de parada'

Especifica a data e a hora em que o rastreamento será interrompido. @stoptime é datetime, com um padrão de NULL. Se NULL, o rastreamento é executado até que seja interrompido manualmente ou até que o servidor seja desligado.

Se @stoptime e @maxfilesize forem especificados e TRACE_FILE_ROLLOVER não forem especificados, o rastreamento será superior quando o tempo de interrupção especificado ou o tamanho máximo do arquivo for atingido. Se @stoptime, @maxfilesize e TRACE_FILE_ROLLOVER forem especificados, o rastreamento será interrompido no tempo de parada especificado, supondo que o rastreamento não preencha a unidade.

@filecount [ = ] 'contagem de arquivos'

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

Por exemplo, quando o parâmetro @tracefile é 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 @filecount estiver definido como 2, o SQL Server excluirá o arquivo C:\mytrace_123.trc antes de criar o arquivo C:\mytrace_125.trcde rastreamento.

O SQL Server tenta excluir cada arquivo apenas uma vez e não pode excluir um arquivo que está em uso por outro processo. Portanto, se outro aplicativo estiver trabalhando com arquivos de rastreamento enquanto o rastreamento estiver 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 você pode 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 do SQL Server que executa muitas das ações executadas anteriormente por 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. Esse 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_*) são estritamente tipados. Se esses parâmetros não forem chamados com os tipos de dados de parâmetro de entrada corretos, conforme especificado na descrição do argumento, o procedimento armazenado retornará um erro.

Para sp_trace_create, a conta de serviço do SQL Server deve ter permissão de gravação na pasta do arquivo de rastreamento. Se a conta de serviço do SQL Server não for um administrador no computador em que o arquivo de rastreamento está localizado, você deverá conceder explicitamente permissão de gravação à 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 do fn_trace_gettable sistema. Para obter mais informações, consulte sys.fn_trace_gettable.

Para obter um exemplo de como usar procedimentos armazenados de rastreamento, consulte Criar um rastreamento.

TRACE_PRODUCE_BLACKBOX tem as seguintes características:

  • É um rastreamento de capotamento. O @filecount padrão é 2, mas pode ser substituído pelo usuário usando @filecount opção.

  • O @maxfilesize padrão, como acontece com outros rastreamentos, é de 5 MB e pode ser alterado.

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

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

    • RPC começando
    • Início em lote
    • Exceção
    • Atenção

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

  • Os filtros não podem ser especificados para esse rastreamento.

Permissões

Requer permissão ALTER TRACE.

Conteúdo relacionado