XAP

Dump

The dump feature of the Admin API allows to easily generate dump information from the GigaSpaces runtime environment. Here is an example:

Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();

// wait a bit for components to be discovered (or use waitFor) ...

DumpResult dumpResult = admin.dump("reason comes here", null,"summary", "thread", "log", "processingUnits");
dumpResult.download(new File("target/dump.zip"), null);

The above example will go over all the currently discovered runtime elements in GigaSpaces (GSAClosed Grid Service Agent. This is a process manager that can spawn and manage Service Grid processes (Operating System level processes) such as The Grid Service Manager, The Grid Service Container, and The Lookup Service. Typically, the GSA is started with the hosting machine's startup. Using the agent, you can bootstrap the entire cluster very easily, and start and stop additional GSCs, GSMs and lookup services at will., GSMClosed Grid Service Manager. This is is a service grid component that manages a set of Grid Service Containers (GSCs). A GSM has an API for deploying/undeploying Processing Units. When a GSM is instructed to deploy a Processing Unit, it finds an appropriate, available GSC and tells that GSC to run an instance of that Processing Unit. It then continuously monitors that Processing Unit instance to verify that it is alive, and that the SLA is not breached., GSCClosed Grid Service Container. This provides an isolated runtime for one (or more) processing unit (PU) instance and exposes its state to the GSM., LUSClosed Lookup Service. This service provides a mechanism for services to discover each other. Each service can query the lookup service for other services, and register itself in the lookup service so other services may find it.) and generate a dump of them (stored locally to each runtime component). Then, the DumpResult can be used to download all the dump information, from all the different runtime components, into a file.

The above example generates dump that will include a simple "summary" information (JVMClosed Java Virtual Machine. A virtual machine that enables a computer to run Java programs as well as programs written in other languages that are also compiled to Java bytecode. information and stats, for example), a thread dump, all the logs associated with the given runtime component, and all the processing unitClosed This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity. instances running (applied to a GSC).

Dump Provider

Most of the elements within the Admin API implement the DumpProvider interface, allowing to generate dump information. This include discrete elements such as GridServiceContainer, or GridServiceManager, but also includes compound elements such as GridServiceManagers and even Admin. This means that quite easily, a dump for a one or more runtime components already grouped by the Admin API can be easily performed. Here are some examples:

Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();

// wait a bit for components to be discovered (or use waitFor) ...

// dump all the GSMs
DumpResult dumpResult = admin.getGridServiceManagers().dump("reason comes here", null,"summary", "thread", "log", "processingUnits");
dumpResult.download(new File("target/gsms.zip"), null);

// dump all the GSCs
dumpResult = admin.getGridServiceContainers().dump("reason comes here", null,"summary", "thread", "log", "processingUnits");
dumpResult.download(new File("target/gscs.zip"), null);

dumpResult = admin.getZones().getByName("zoneA").dump("reason comes here", null,"summary", "thread", "log", "processingUnits");
dumpResult.download(new File("target/zoneA.zip"), null);

If the natural grouping provided by the admin API is not enough, then the CompoundDumpResult can be used in order to accumulate dump results. Here is an example:

CompoundDumpResult dumpResult = new CompoundDumpResult();
dumpResult.add(gridServiceContainer1.dump(...));
dumpResult.add(gridServiceManager2.dump(...));
dumpResult.add(gridServiceAgent3.dump(...));

dumpResult.download(new File("target/compound.zip", null);

Dump Processors

The dump process occurs in stages within the runtime component. Each stage is called a processor and the following is a list of all the different processors:

Type Description
summary General summary information of the process.
network Information on the network layer of the process and the OS network stats.
thread Thread dump of the process.
heap Heap dump of the process. Note, this is a heavy operation and can produce very large dump files.
log Adds all the log files of the process to the dump file.
processingUnits Dump of all the processing units (applicable only for GSCs) information.

The log process is the only processor that takes into account the context (Map<String, Object>) that can be passed as part of the dump command. It tries to find under the logEntryMatcher key a LogEntryMatcher that will be used to filter out just relevant parts of the log files to be returned. If no matcher is provided, all the log files will be returned. Here is an example of specifying a log entry matcher:

Map<String, Object> context = new HashMap<String, Object>();
context.put("logEntryMatcher", lastN(200));
DumpResult dumpResult = admin.generateDump("test", context, "summary", "log");

The above code will generate a dump, including the last 200 log entries which the log dump processor will process.

Dump File Structure

The dump file structure would look like this:

dump_file.zip

    gsa-10.10.10.249-23610--1284928573201
        network.txt
        summary.txt
        threads.txt
        logs
            2010-09-19~08.22-gigaspaces-gsa-10.10.10.249-23610.log

    gsc-10.10.10.249-23739--1284928573169
        network.txt
        summary.txt
        threads.txt
        logs
            2010-09-19~08.22-gigaspaces-gsc_1-10.10.10.249-23739.log
        processing-units
            space
                1
                    puClosed This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity..xml
                    spaces
                        space
                            summary.txt

    gsc-10.10.10.249-23766--1284928573079
        network.txt
        summary.txt
        threads.txt
        logs
            2010-09-19~08.22-gigaspaces-gsc_2-10.10.10.249-23766.log
        processing-units
            mirror
                1
                    pu.xml
                    spaces
                        mirror
                            summary.txt
            space
                1_1
                    pu.xml
                    spaces
                        space
                            summary.txt

    gsm-10.10.10.249-24112--1284928573193
        network.txt
        summary.txt
        threads.txt
        logs
            2010-09-19~08.22-gigaspaces-gsm_3-10.10.10.249-24112.log
    lus-10.10.10.249-24127--1284928573201
        network.txt
        summary.txt
        threads.txt
        logs
            2010-09-19~08.22-gigaspaces-lus_4-10.10.10.249-24127.log

Dump Configuration

You can configure GigaSpaces to generate a heap dump when memory shortage occurs.

Property name Description Default
com.gs.memory.create-heap-dump-on-memory-shortage Turn on and off heap dump false
com.gs.memory.max-heaps-on-memory-shortage Turn off the heap dump after n times 1
com.gs.memory.heaps-on-memory-shortage-quiet-period How much time to wait between heap dumps 24h

These values can be modified using the JConsole using the HeapDumpMBean with ObjectName org.xap:type=HeapDumpMBean Refer to JMX Management

GigaSpaces Management Center

The GigaSpaces Management Center has been deprecated and will be removed in a future release.

The dump can be created via the GigaSpaces Management Center.

Web Management Console

The dump can be created via the Web Management Console.

Ops Manager

You can generate a service log dump from GigaSpaces Ops Manager.