Implementando log em pacotes

O Integration Services inclui recursos de log que gravam entradas de log quando eventos de tempo de execução ocorrem e que também podem gravar mensagens personalizadas.

O Integration Services dá suporte a um conjunto variado de provedores de log e permite que você crie provedores de log personalizados. O provedor de log do Integration Services pode gravar entradas de log em arquivos de texto, arquivos do SQL Server Profiler, do SQL Server, de Log de Eventos do Windows ou XML.

Logs são associados a pacotes e são configurados no nível de pacote. Cada tarefa ou contêiner em um pacote pode registrar informações em qualquer log de pacote. As tarefas e os contêineres em um pacote podem ser habilitados para registro mesmo se o próprio pacote não for habilitado para isso. Por exemplo, você pode habilitar o registro em uma tarefa Executar SQL sem habilitar o registro no pacote pai. Um pacote, contêiner ou tarefa pode gravar em vários logs. Você só pode habilitar o registro no pacote ou optar por habilitar o registro em qualquer tarefa ou contêiner individual que o pacote inclua.

Para personalizar o registro de um evento ou mensagem personalizada, o Integration Services fornece um esquema de informações com logs comuns a ser incluído em entradas de log. O esquema de log do Integration Services define as informações que podem ser registradas. Você pode selecionar elementos do esquema de log para cada entrada de log.

Um pacote e seus contêineres e tarefas não precisam registrar as mesmas informações; e as tarefas dentro do mesmo pacote ou contêiner podem registrar informações diferentes. Por exemplo, um pacote pode registrar informações do operador quando for iniciado, uma tarefa pode registrar a origem da falha da tarefa e outra tarefa pode registrar informações quando ocorrerem erros. Se um pacote e seus contêineres e tarefas usarem vários logs, as mesmas informações serão gravadas em todos os logs.

Você pode selecionar um nível de registro que se adapte às suas necessidades especificando os eventos e as informações a serem registrados para cada evento. Você pode achar que alguns eventos fornecem informações mais úteis que outros. Por exemplo, você talvez queira registrar apenas os nomes de computador e operador para o evento PreExecute, mas todas as informações disponíveis para o evento Error.

Para evitar que arquivos de log usem grandes quantidades de espaço em disco ou para evitar o registro excessivo, que pode degradar o desempenho, limite o registro selecionando eventos específicos e itens de informações a serem registrados. Por exemplo, você pode configurar um log para capturar só a data e o nome do computador para cada erro.

No Designer SSIS, você define as opções de log usando a caixa de diálogo Configurar Logs de SSIS.

Esquema de log

A tabela a seguir descreve os elementos no esquema de log.

Elemento

Descrição

Computer

O nome do computador no qual o evento de log ocorreu.

Operator

A identidade do usuário que iniciou o pacote.

SourceName

O nome do contêiner ou tarefa no qual o evento de log ocorreu.

SourceID

O identificador exclusivo do pacote; o contêiner Loop For, Loop Foreach ou Sequência ou a tarefa na qual o evento de log ocorreu.

ExecutionID

O GUID da instância de execução do pacote.

ObservaçãoObservação
A execução de um pacote simples pode criar entradas de log com valores diferentes para o elemento ExecutionID. Por exemplo, quando você executa um pacote no BI Development Studio, a fase de validação talvez crie entradas de log com um elemento ExecutionID que corresponde ao BI Development Studio. No entanto, a fase de execução talvez crie entradas de log com um elemento ExecutionID correspondente a dtshost.exe. Para obter outro exemplo, quando você executa um pacote que contém tarefas Executar Pacote, cada uma dessas tarefas executa um pacote filho. Esses pacotes filho podem criar entradas de log com um elemento ExecutionID diferente do das entradas de log criadas pelo pacote pai.

MessageText

Uma mensagem associada à entrada de log.

DataBytes

Uma matriz de bytes específica para a entrada de log. O significado deste campo varia de acordo com a entrada de log.

A tabela a seguir descreve três elementos adicionais no esquema de log que não estão disponíveis na guia Detalhes da caixa de diálogo Configurar Logs de SSIS.

Elemento

Descrição

StartTime

A hora em que o contêiner ou tarefa começa a ser executado.

EndTime

A hora em que a execução do contêiner ou tarefa para.

DataCode

Um valor inteiro opcional que geralmente contém um valor da enumeração DTSExecResult que indica o resultado da execução do contêiner ou da tarefa:

  • 0 - Êxito

  • 1 - Falha

  • 2 - Concluído

  • 3 - Cancelado

Entradas de log

O Integration Services dá suporte a entradas de log em eventos predefinidos e fornece entradas de log personalizadas para muitos objetos do Integration Services. A caixa de diálogo Configurar Logs de SSIS no Designer SSIS lista esses eventos e entradas de log personalizadas.

A tabela a seguir descreve os eventos predefinidos que podem ser habilitados a gravar entradas de log quando eventos de tempo de execução ocorrem. Essas entradas de log se aplicam a executáveis, ao pacote e às tarefas e contêineres que o pacote inclui. O nome da entrada de log é igual ao nome do evento de tempo de execução que foi gerado e fez com que a entrada de log fosse gravada.

Eventos

Descrição

OnError

Grava uma entrada de log quando ocorre um erro.

OnExecStatusChanged

Grava uma entrada de log quando o status da execução do executável é alterado.

OnInformation

Grava uma entrada de log durante a validação e execução de um executável para relatar informações.

OnPostExecute

Grava uma entrada de log imediatamente depois que o executável termina de ser executado.

OnPostValidate

Grava uma entrada de log quando a validação do executável termina.

OnPreExecute

Grava uma entrada de log imediatamente antes da execução do executável.

OnPreValidate

Grava uma entrada de log quando a validação do executável inicia.

OnProgress

Grava uma entrada de log quando o progresso mensurável é feito pelo executável.

OnQueryCancel

Grava uma entrada de log em qualquer ligação no processamento de tarefa no qual é possível cancelar a execução.

OnTaskFailed

Grava uma entrada de log quando uma tarefa falha.

OnVariableValueChanged

Grava uma entrada de log quando o valor de uma variável é alterado.

OnWarning

Grava uma entrada de log quando ocorre um aviso.

PipelineComponentTime

Para cada componente de fluxo de dados, grava uma entrada de log para cada fase de validação e execução. A entrada de log especifica o tempo de processamento de cada fase.

Diagnostic

Grava uma entrada de log que fornece informações de diagnóstico.

Por exemplo, você pode registrar uma mensagem antes e depois de cada chamada para um provedor de dados externo. Para obter mais informações, consulte Solucionando problemas de execução do pacote.

O pacote e muitas tarefas têm entradas de log personalizadas que podem ser habilitadas para registro. Por exemplo, a tarefa Enviar Email fornece a entrada de log personalizada SendMailTaskBegin, que registra informações quando a tarefa Enviar Email começa a ser executada, mas antes de a tarefa enviar uma mensagem de email. Para obter mais informações, consulte Mensagens personalizadas para log.

Diferenciando cópias de pacotes

Os dados de log incluem o nome e o GUID do pacote ao qual as entradas de log pertencem. Se você criar um novo pacote copiando um pacote existente, o nome e o GUID do pacote existente também serão copiados. Como resultado, você pode ter dois pacotes com o mesmo GUID e nome, dificultando a diferenciação entre eles nos dados de log.

Para eliminar essa ambiguidade, você deve atualizar o nome e o GUID dos novos pacotes. No Business Intelligence Development Studio, você pode gerar o GUID novamente na propriedade ID e atualizar o valor da propriedade Name na janela Propriedades. Você também pode alterar o GUID e o nome programaticamente ou usando o prompt de comando dtutil . Para obter mais informações, consulte Definindo propriedades do pacote e Utilitário dtutil (ferramenta SSIS).

Opções de log pai

Geralmente, as opções de log de tarefas e os contêineres Loop For, Loop Foreach e Sequência correspondem às opções do pacote ou de um contêiner pai. Nesse caso, você pode configurá-las para herdar as opções de log de seus contêineres pai. Por exemplo, em um contêiner Loop For que inclui uma tarefa Executar SQL, essa tarefa pode usar as opções de log que são definidas no contêiner Loop For. Para usar as opções de log pai, defina a propriedade LoggingMode do contêiner como UseParentSetting. É possível definir essa propriedade na janela Propriedades do Business Intelligence Development Studio ou através da caixa de diálogo Configurar Logs de SSIS no Designer SSIS.

Modelos de log

Na caixa de diálogo Configurar Logs de SSIS, você também pode criar e salvar configurações de log usadas com frequência como modelos e depois usar esses modelos em vários pacotes. Isso facilita a aplicação de uma estratégia de log consistente entre vários pacotes e a modificação de definições de log nos pacotes atualizando e depois aplicando os modelos. Os modelos são armazenados em arquivos XML.

Para configurar o registro usando a caixa de diálogo Configurar Logs de SSIS

  1. Habilite o pacote e suas tarefas para registrar. O registro pode ocorrer no nível de pacote, contêiner e tarefa. Você pode especificar logs diferentes para pacotes, contêineres e tarefas.

  2. Selecione um provedor de log e adicione um log ao pacote. Os logs podem ser criados apenas no nível de pacote, e uma tarefa ou contêiner deve usar um dos logs criados para esse pacote. Cada log é associado a um dos seguintes provedores de log: arquivo de texto, SQL Server Profiler, SQL Server, Log de Eventos do Windows ou arquivo XML. Para obter mais informações, consulte Como habilitar registros em um pacote.

  3. Selecione os eventos e as informações de esquema de log sobre cada evento que você deseja capturar no log. Para obter mais informações, consulte Como configurar o log usando um arquivo de configuração salvo.

Para exibir entradas de log durante o desenvolvimento de pacote

Recursos externos

Ícone do Integration Services (pequeno) Fique atualizado com o Integration Services

Para obter os downloads, artigos, exemplos e vídeos mais recentes da Microsoft, bem como soluções selecionadas da comunidade, visite a página do Integration Services no MSDN ou TechNet:

Para receber uma notificação automática sobre essas atualizações, assine os feeds RSS disponíveis na página.