Creating, Editing, and Uploading Custom Incident Packages

About Correlated Diagnostic Data in Incident Packages

To diagnose problem, it is sometimes necessary to examine not only diagnostic data that is directly related to the problem, but also diagnostic data that is correlated with the directly related data. Diagnostic data can be correlated by time, by process ID, or by other criteria. For example, when examining an incident, it may be helpful to also examine an incident that occurred five minutes after the original incident. Similarly, while it is clear that the diagnostic data for an incident should include the trace file for the Oracle Database process that was running when the incident occurred, it might be helpful to also include trace files for other processes that are related to the original process.

Thus, when problems and their associated incidents are added to a package, any correlated incidents are added at the same time, with their associated trace files.

During the process of creating the physical file for a package, the Support Workbench calls upon the Incident Packaging Service to finalize the package. Finalizing means adding to the package any additional trace files that are correlated by time to incidents in the package, and adding other diagnostic information such as the alert log, health checker reports, SQL test cases, configuration information, and so on. This means that the number of files in the zip file may be greater than the number of files that the Support Workbench had previously displayed as the package contents.

The Incident Packaging Service follows a set of rules to determine the trace files in the ADR that are correlated to existing package data. You can modify some of those rules in the Incident Packaging Configuration page in Enterprise Manager.

Because both initial package data and added correlated data may contain sensitive information, it is important to have an opportunity to remove or edit files that contain this information before uploading to Oracle Support. For this reason, the Support Workbench enables you to run a command that finalizes the package as a separate operation. After manually finalizing a package, you can examine the package contents, remove or edit files, and then generate and upload a zip file.

About Quick Packaging and Custom Packaging

The Enterprise Manager Support Workbench provides two methods for creating and uploading an incident package: the quick packaging method and the custom packaging method.

Quick Packaging—This is the more automated method with a minimum of steps, organized in a guided workflow (a wizard). You select a single problem, provide a package name and description, and then schedule upload of the package contents, either immediately or at a specified date and time. The Support Workbench automatically places diagnostic data related to the problem into the package, finalizes the package, creates the zip file, and then uploads the file. With this method, you do not have the opportunity to add, edit, or remove package files or add other diagnostic data such as SQL test cases. However, it is the simplest and quickest way to get first-failure diagnostic data to Oracle Support. Quick packaging is the method used in the workflow described in "Investigating, Reporting, and Resolving a Problem".

Note that when quick packaging is complete, the package that was created by the wizard remains. You can then modify the package with custom packaging operations at a later time and manually reupload.

Custom Packaging—This is the more manual method, with more steps. It is intended for expert Support Workbench users who want more control over the packaging process. With custom packaging, you can create a new package with one or more problems, or you can add one or more problems to an existing package. You can then perform a variety of operations on the new or updated package, including:

• Adding or removing problems or incidents

• Adding, editing, or removing trace files in the package

• Adding or removing external files of any type

• Adding other diagnostic data such as SQL test cases

• Manually finalizing the package and then viewing package contents to determine if you must edit or remove sensitive data or remove files to reduce package size.

You might conduct these operations over a number of days, before deciding that you have enough diagnostic information to send to Oracle Support.

With custom packaging, you create the zip file and request upload to Oracle Support as two separate steps. Each of these steps can be performed immediately or scheduled for a future date and time.

About Correlated Packages

Correlated packages provide a means of packaging and uploading diagnostic data for related problems. A database instance problem can have related problems in other database instances or in Oracle Automatic Storage Management instances, as described in "Related Problems Across the Topology". After you create and upload a package for one or more database instance problems (the "main package"), you can create and upload one or more correlated packages, each with one or more related problems. You can accomplish this only with the custom packaging workflow in Enterprise Manager Support Workbench.

Viewing Package Details

The Package Details page contains information about the incidents, trace files, and other files in a package, and enables you to view and add to the package activity log.

To view package details:

1. Access the Support Workbench home page.

   See "Viewing Problems with the Enterprise Manager Support Workbench" for instructions.

2. Click the Packages link to view the Packages subpage.

   A list of packages that are currently in the Automatic Diagnostic Repository (ADR) is displayed.

3. (Optional) To reduce the number of packages displayed, enter text into the Search field above the list, and then click Go.

   All packages that contain the search text anywhere in the package name are displayed. To view the full list of packages, click the Packages link again.

4. Under the Package Name column, click the link for the desired package.

   The Package Details page appears.

Accessing the Customize Package Page

The Customize Package page is used to perform various packaging tasks, such as adding and removing problems; adding, removing, and scrubbing (editing) package files; and generating and uploading the package zip file.

To access the Customize Package page:

1. Access the Package Details page for the desired package, as described in "Viewing Package Details".

2. Click Customize Package.

   The Customize Package page appears.

Editing Incident Package Files (Copying Out and In)

The Support Workbench enables you to edit one or more files in an incident package. You may want to do this to delete or overwrite sensitive data in the files. To edit package files, you must first copy the files out of the package into a designated directory, edit the files with a text editor or other utility, and then copy the files back into the package, overwriting the original package files.

The following procedure assumes that the package is already created and contains diagnostic data.

To edit incident package files:

1. Access the Customize Package page for the desired incident package.

   See "Accessing the Customize Package Page" for instructions.

2. In the Packaging Tasks section, under the Scrub User Data heading, click Copy out Files to Edit contents.

   The Copy Out Files page appears. It displays the name of the host to which you can copy files.

   Figure 9-8 Copy Out Files Page

   
   Description of "Figure 9-8 Copy Out Files Page"
   
   

3. Do one of the following to specify a destination directory for the files:

   • Enter a directory path in the Destination Folder field.

   • Click the flashlight icon next to the Destination Folder field, and then complete the following steps:

     1. If prompted for host credentials, enter credentials for the host to which you want to copy out the files, and then click OK. (Select Save as Preferred Credential to avoid the prompt for credentials next time.)

     2. In the Browse and Select File or Directory window, click directory links to move down the directory hierarchy, and click directory names next to the Path label to move up the directory hierarchy, until you see the desired destination directory.

        
        Description of the illustration package_browse_and_select.gif
        
        

        To reduce the number of directories displayed in the list, enter search text in the Search field and click Go. All directories that have the search text anywhere in the directory name are displayed.

     3. Select the desired destination directory, and then click Select.

        The Browse and Select File or Directory window closes, and the path to the selected directory appears in the Destination Folder field of the Copy Out Files page.

4. Under Files to Copy Out, select the desired files, and then click OK.

   Note:

   If you do not see the desired files, they may be on another page. Click the Next link to view the next page. Continue clicking Next, or select from the list of file numbers (to the left of the Next link) until you see the desired files. You can then select the files and click OK.

   The Customize Package page returns, displaying a confirmation message that lists the files that were copied out.

5. Using a text editor or other utility, edit the files.

6. On the Customize Package page, in the Packaging Tasks section, under the Scrub User Data heading, click Copy in Files to Replace Contents.

   The Copy In Files page appears. It displays the files that you copied out.

7. Select the files to copy in, and then click OK.

   The files are copied into the package, overwriting the existing files. The Customize Package page returns, displaying a confirmation message that lists the files that were copied in.

Adding an External File to an Incident Package

You can add any type of external file to an incident package.

To add an external file to an incident package:

1. Access the Customize Package page for the desired incident package.

   See "Accessing the Customize Package Page" for instructions.

2. Click the Files link to view the Files subpage.

   Figure 9-9 Files Subpage of Customize Package Page

   
   Description of "Figure 9-9 Files Subpage of Customize Package Page"
   
   

   From this page, you can add and remove files to and from the package.

   Note:

   The View list appears only for packages for which you already created a physical file. It enables you to view either incremental package contents or the full package contents. The default selection is incremental package contents. This default selection displays only those package files that were created or modified since the last time that a physical file was generated for the package.

3. Click Add external files.

   The Add External File page appears. It displays the host name from which you may select a file.

4. Do one of the following to specify a file to add:

   • Enter the full path to the file in the File Name field.

   • Click the flashlight icon next to the File Name field, and then complete the following steps:

     1. If prompted for host credentials, enter credentials for the host on which the external file resides, and then click OK. (Select Save as Preferred Credential to avoid the prompt for credentials next time.)

     2. In the Browse and Select File or Directory window, click directory links to move down the directory hierarchy, and click directory names next to the Path label to move up the directory hierarchy, until you see the desired file.

        
        Description of the illustration package_browse_and_select.gif
        
        

        To reduce the number of files or directories displayed in the list, enter search text in the Search field and click Go. All files or directories that have the search text anywhere in the file name or directory name are displayed.

     3. In the Select column, click to select the desired file, and then click Select.

        The Browse and Select window closes, and the path to the selected file appears in the File Name field of the Add External File page.

5. Click OK.

   The Customize Package page returns, displaying the Files subpage. The selected file is now shown in the list of files.

Removing Incident Package Files

You can remove one or more files of any type from the incident package.

To remove incident package files:

1. Access the Customize Package page for the desired incident package.

   See "Accessing the Customize Package Page" for instructions.

2. Click the Files link to view the Files subpage.

   A list of files in the package is displayed.

   If you have not yet generated a physical file for this package, all package files are displayed in the list. If you have already generated a physical file, a View list appears above the files list. It enables you to choose between viewing only incremental package contents or the full package contents. The default selection is incremental package contents. This default selection displays only those package files that were created or modified since the last time that a physical file was generated for the package. Select Full package contents from the View list to view all package files.

3. Select the files to remove, and then click Exclude.

   Note:

   If you do not see the desired files, they may be on another page. Click the Next link to view the next page. Continue clicking Next, or select from the list of file numbers (to the left of the Next link) until you see the desired files. You can then select the files and click Remove.

Viewing and Updating the Incident Package Activity Log

The Support Workbench maintains an activity log for each incident package. Most activities that you perform on a package, such as adding or removing files or creating a package zip file, are recorded in the log. You can also add your own notes to the log. This is especially useful if more than one database administrator is working with packages.

To view and update the incident package activity log:

1. Access the Package Details page for the desired incident package.

   See "Accessing the Customize Package Page" for instructions.

2. Click the Activity Log link to view the Activity Log subpage.

   The activity log is displayed.

3. To add your own note to the activity log, enter text into the Note field, and then click Add Note.

   Your note is timestamped and appended to the list.