Partilhar via

sp_trace_create (Transact-SQL)

Aplica-se a:SQL Server

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

Importante

Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em novos trabalhos de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso. Em vez disso, use Eventos estendidos.

Transact-SQL convenções de sintaxe

Sintaxe

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

Argumentos

Importante

Os argumentos para procedimentos armazenados estendidos devem ser inseridos na ordem específica, conforme descrito na seção de sintaxe. Se os parâmetros forem inseridos fora de ordem, ocorrerá uma mensagem de erro.

[ @traceid = ] SAÍDA TRACEID

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 este procedimento armazenado.

[ @options = ] opções

Especifica as opções definidas 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 selecionadas. 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, descrições e seus valores.

Nome da opção Valor da 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 inteiro é acrescentado 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 seguinte arquivo de rastreamento será filename_2.trce assim por diante.

À medida que mais arquivos de rastreamento de sobreposição são criados, o valor inteiro anexado ao nome do arquivo aumenta sequencialmente.

O SQL Server usa 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 extensão .trc a todos os nomes de arquivo de rastreamento. Se a opção TRACE_FILE_ROLLOVER 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 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 nomeado filename.trc, o segundo arquivo de rastreamento será nomeado filename_1.trc.

Se você usar a opção TRACE_FILE_ROLLOVER, 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 automaticamente nem solicita que você carregue os arquivos de substituição (se qualquer 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) onde 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 automaticamente acrescentados quando um arquivo é substituído.)

Observação

Como solução alternativa para ambos os comportamentos, você pode renomear os arquivos para remover os sublinhados no nome do 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 abrir os arquivos no SQL Server Profiler.

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

[ @maxfilesize = ] maxfilesize

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

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

[ @stoptime = ] 'tempo de paragem'

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é ser interrompido manualmente ou até que o servidor seja desligado.

Se @stoptime e @maxfilesize forem especificados 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 @stoptime, @maxfilesizee TRACE_FILE_ROLLOVER forem especificados, o rastreamento para na hora de parada especificada, supondo que o rastreamento não preencha a unidade.

[ @filecount = ] 'filecount'

Especifica o número máximo ou arquivos de rastreamento a serem mantidos com o mesmo nome de arquivo base. @filecount é int, maior que 1. Este parâmetro só é válido se a opção TRACE_FILE_ROLLOVER for especificada. Quando @filecount é especificado, o SQL Server tenta manter apenas @filecount arquivos de rastreamento excluindo o arquivo de rastreamento mais antigo antes de abrir um novo arquivo de rastreamento. O SQL Server controla a idade dos arquivos de rastreamento anexando 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 de rastreamento C:\mytrace_125.trc.

O SQL Server só tenta excluir cada arquivo 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 de 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 Sem 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 Tempo de paragem inválido. Retornado quando o tempo de parada especificado já tiver acontecido.
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. 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_*) são estritamente digitados. Se esses parâmetros não forem chamados com os tipos de dados de parâmetros 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 gravar na pasta do arquivo 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ê 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 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 rastro de capotamento. O @filecount padrão é 2, mas pode ser substituído pelo usuário usando @filecount opção.

  • O @maxfilesizepadrão, assim como outros rastreamentos, é de 5 MB e pode ser alterado.

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

  • Somente os seguintes eventos e suas colunas estão contidos no rastreamento:

    • RPC começando
    • Lote iniciando
    • Exceção
    • Atenção

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

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

Permissões

Requer permissão ALTER TRACE.

Conteúdo relacionado

  • Last updated on