Administrative and configuration operations make it possible to check Dgraph statistics, and enable or disable diagnostic flags without having to stop a running Dgraph. They also let you stop and restart the Dgraphs. This section lists URLs exposed by the Dgraph, describes the functions of each URL, and defines the syntax of those URLs.
The syntax for Dgraph URL operations is documented below. Queries to these URLs are handled in the MDEX Engine's request queue like any other request—that is, they are handled on a first-come, first-served basis. They are also reported in the MDEX Engine request log like any other request.
In the
following blocks,
<mdex_host> refers to the hostname or IP address
of the MDEX Engine and
<mdex_port> refers to the port on which the MDEX
Engine is listening.
For administrative operations, the syntax is:
http[s]://<mdex_host>:<mdex_port>/admin?op=<supported-operation>
For configuration operations, the syntax is:
http[s]://<mdex_host>:<mdex_port>/config?op=<supported-operation>
Administrative (or admin) operations listed in this topic allow you to control the behavior of the MDEX Engine from within the system.
The MDEX Engine recognizes the following admin operations:
|
Admin operation |
Description |
|---|---|
|
|
Returns the usage page for all of the admin operations. |
|
|
Checks the aliveness of an MDEX Engine and returns a lightweight message. |
|
|
Specifies when the MDEX Engine should flush its dynamic cache. |
|
|
Stops a running MDEX Engine. |
|
|
Restarts the MDEX Engine. |
|
|
Returns the MDEX Engine Auditing page. |
|
|
Resets the MDEX Engine Auditing page. |
|
|
Returns the MDEX Engine Statistics page. |
|
|
Resets the MDEX Engine Statistics page. |
|
|
Forces a query log roll, with the side effect
of remapping
|
|
|
Applies any partial update files to the MDEX Engine. |
|
|
Rebuilds the aspell dictionary for spelling correction from the data corpus without stopping and restarting the MDEX Engine. |
|
|
Shows a list of the update files that the MDEX Engine has processed recently. |
|
|
A Web services operation that reloads the application's main and library modules. |
/admin?op=ping checks the aliveness of an MDEX
Engine and returns a lightweight message.
You can view the MDEX Engine Statistics page
to check whether the MDEX Engine is running and accepting queries, but that
comes with some overhead. A quicker way to check the availability of a Dgraph
is by running the
ping command.
The
ping command returns a lightweight page that lists the
MDEX Engine, the current date and time, such as the following:
dgraph example.endeca.com:8000 responding at Wed Oct 25 15:35:27 2009
You can use this operation to monitor the availability of the MDEX Engine, and as an availability check for load balancers.
/admin?op=flush flushes the Dgraph cache.
The
flush operation clears all entries from the Dgraph
cache. It returns the following message:
flushing cache...
/admin?op=exit stops a running MDEX Engine.
The
exit operation puts the Dgraph on hold while all
outstanding transactions (queries) are completed. Once all transactions have
been completed, the Dgraph shuts down. This is the recommended way to shut down
a Dgraph, as opposed to manually killing the process, since it gracefully
completes all transactions and exits cleanly.
The output looks similar to the following:
Dgraph admin, OK Dgraph shutting down at Wed May 20 11:23:08 2009
Both the Oracle Endeca Application Controller (EAC) and the deprecated
Control Interpreter use the
exit operation behind the scenes to stop an MDEX Engine.
However, if the MDEX Engine in question was originally started by the EAC or
the Control Interpreter, manually submitting this operation fails to
permanently shut down the MDEX Engine, because the EAC or the Control
Interpreter interprets the resulting MDEX Engine shutdown as a failure and
restarts it immediately. MDEX Engines started by the EAC or the Control
Interpreter should be shut down through the control framework that originally
started them.
/admin?op=restart restarts the Dgraph.
The
restart operation acts similarly to the
exit operation, except that after shutting down, the
Dgraph restarts. This is the recommended way to restart a Dgraph, as opposed to
manually stopping and starting the process, since it gracefully completes all
transactions and exits cleanly before starting up again.
The
restart operation returns output similar to the
following:
Dgraph admin, OK Dgraph restarting at Wed May 20 11:25:19 2009
/admin?op=audit returns the MDEX Engine Auditing
page.
The MDEX Engine Auditing page lets you view the aggregate Dgraph metrics over time. It provides the output of XML reports that track ongoing usage statistics. These statistics persist through process restarts. This data can be used to verify compliance with licensing terms, and is also useful for tracking product usage.
Note
For details about the MDEX Engine Auditing page, see the Performance Tuning Guide.
/admin?op=auditreset resets the MDEX Engine
Auditing page.
It returns the following message:
resetting auditing stats...
/admin?op=stats returns the MDEX Engine
Statistics page.
The MDEX Engine Statistics page provides a detailed breakdown of what the Dgraph is doing, and is a useful source of information about your Endeca implementation’s configuration and performance. It provides information such as startup time, last data indexing time, and indexing data path. This lets you focus your tuning and load-balancing efforts. By examining this page, you can see where the Dgraph is spending its time. Begin your tuning efforts by identifying the features on the Details tab Hotspots section with the highest totals.
Note
For details about the MDEX Engine Statistics page, see the Performance Tuning Guide.
/admin?op=statsreset resets the MDEX Engine
Statistics page.
The
statsreset operation returns the following message:
resetting server stats...
/admin?op=logroll forces a query log roll, with
the side effect of remapping
stdout.
The
logroll command returns a message similar to the
following:
rolling log... Successfully remapped stdout/stderr to specified path "C:\Endeca\apps\JanWine\logs\dgraphs\Dgraph2\Dgraph2.log". Successfully rolled log file.
/admin?op=update applies any partial update files
to the Dgraph.
This operation instructs the Dgraph to process the partial update files in its update directory. For more information on partial updates, see the Partial Updates Guide.
On receiving the URL update command, the Dgraph by default performs the following sequence of operations:
In some cases, you may need to run a partial update by pointing the
Dgraph to a single file. In this case, run the
admin?op=update&updatefile=
option where
filename
filename is the name of an update file residing in the
update directory.
If you have more than one file, rerun this command. The update file is deleted after the MDEX Engine successfully applies the results of the partial update.
The
admin?op=updateaspell administrative operation lets you
rebuild the aspell dictionary for spelling correction from the data corpus
without stopping and restarting the MDEX Engine.
The
admin?op=updateaspell operation performs the following
actions:
Converts this word list to the binary format required by
aspellCauses the Dgraph to finish processing all existing preceding queries and temporarily stop processing incoming queries
Replaces the previous binary format word list with the updated binary format word list
Causes the Dgraph to resume processing queries waiting in the queue
The Dgraph applies the updated settings without needing to restart.
Only one
admin?op=updateaspell operation can be processed at a
time.
The
admin?op=updateaspell operation returns output similar
to the following in the Dgraph error log:
... aspell update ran successfully. ...
Note
If you start the Dgraph with the
-v flag, the output also contains a line similar to
the following:
Time taken for updateaspell, including wait time on any previous updateaspell, was 290.378174 ms.
/admin?op=updatehistory shows a list of the
update files that the Dgraph has processed since it was started.
The
updatehistory operation returns output similar to the
following:
Endeca Dgraph Server update directory history contents Checking for update directory for directory "..\data\partition0\dgraph_input\updates\" Files in update directory history "..\data\partition0\dgraph_input\updates\\wine-sgmt0.records.xml_2009.05.19.10.31.25" "..\data\partition0\dgraph_input\updates\\wine-sgmt0.records.xml_2009.05.19.10.30.08" "..\data\partition0\dgraph_input\updates\\wine-sgmt0.records.xml_2009.05.19.10.32.13"
/admin?op=reload-services is a Web services
operation that reloads the application's main and library modules.
The
admin?op=reload-services operation causes the Dgraph to
process all existing preceding queries, temporarily stop processing other
queries and begin to process
admin?op=reload-services. After it finishes processing
this operation, the Dgraph resumes processing queries that queued up
temporarily behind this request.
Note
admin?op=reload-services can be a time-consuming
operation, depending on the number of XQuery modules that you have created and
that have to be compiled.
Configuration (or config) operations listed in this topic allow you to modify configuration and logging information for the MDEX Engine from within the system.
The Dgraph recognizes the following config operations:
|
Config operation |
Description |
|---|---|
|
|
Returns the usage page for all of the config operations. |
|
|
Loads and applies MDEX Engine configuration files from disk.
NoteOracle does not recommend using this operation, as it overwrites any configuration published from Workbench.
|
|
|
Enables verbose logging for one or more specified variables. |
|
|
Disables verbose logging for one or more specified variables. |
|
|
Returns verbose logging status. |
The
config?op=update operation loads any updated Dgraph
configuration files (containing information about items such as thesaurus
entries or dynamic business rules). The Dgraph applies the updated settings
without needing to restart.
The
config?op=update operation causes the Dgraph to drain
all existing preceding queries, temporarily stop processing other queries and
begin to process
config?op=update. The operation loads and applies any
updated configuration files. After it finishes processing these operations, the
Dgraph resumes processing queries that queued up temporarily behind these
requests.
Only one
config?op=update operation can be processed at a time.
This command is useful during development and debugging, when it is desirable
to quickly load configuration changes without the interruption of restarting an
MDEX Engine. It is not recommended when configuration exists in Workbench, as
it uploads files from disk and not from the Endeca Configuration Repository.
Note
The
config?op=update operation can be time consuming,
depending on the number of configuration files the Dgraph has to process for an
update.
The update operation returns output similar to the following:
Processing configuration file "<full path to XML configuration file>" Successfully processed configuration file "<full path to XML configuration file>" Finished processing config updates.
You can use logging variables with config operations. This lets you obtain detailed information about Dgraph processing, to help diagnose unexpected application behavior or performance problems, without stopping and restarting the Dgraph or requiring a configuration update.
Although you can also specify general verbose logging at the Dgraph
command line with the
--v flag, it requires a Dgraph restart to take effect.
MDEX Engine logging variables are toggled using the
/config?op=log-enable&name=
and
<variable-name>
/config?op=log-disable&name=
operations.
<variable-name>
You can include multiple logging variables in a single request. Unrecognized logging variables generate warnings.
For example, this operation:
/config?op=log-enable&name=merchverbose
turns on verbose logging for the dynamic business rule feature, while this operation:
config?op=log-enable&name=textsearchrelrankverbose&name=textsearchspellverbose
turns on verbose logging for both the text search relevance ranking and spelling features.
However, this operation:
config?op=log-enable&name=allmylogs
returns an unsupported logging setting message.
In addition, the following operations are supported:
The following table describes the supported logging variables that you can use with related config operations to toggle logging verbosity for specified features.
Logging variable names are not case sensitive.
|
Variable |
Description |
|---|---|
|
|
Enables verbose mode. |
|
|
Prints information about each request to stdout. |
|
|
Show verbose messages while processing updates. |
|
|
Enables verbose information about record filter performance. |
|
|
Enables verbose debugging messages during merchandising rule processing. |
|
|
Enables verbose information about relevance ranking during search query processing. |
|
|
Enables verbose output for spelling correction features. |
|
|
Enables verbose performance debugging messages during core Dgraph navigation computations. |
|
|
Enables refinement verbose/debugging messages. |
The
log-enable operation lets you turn on verbose logging.
You can include multiple logging variables in a single request. Unrecognized logging variables generate warnings.
For example, this operation:
/config?op=log-enable&name=merchverbose
turns on verbose logging for the dynamic business rule feature, while this operation:
config?op=log-enable&name=textsearchrelrankverbose&name=textsearchspellverbose
turns on verbose logging for both the text search relevance ranking and spelling features.
However, this operation:
config?op=log-enable&name=allmylogs
returns an “unsupported logging setting” message.
The
log-disable operation lets you turn off verbose logging.
/config?op=log-disable with no arguments returns the
same output as
log-status.
The
log-status operation returns a list of all logging
variables with their values (true or false).
For example, if you have not enabled verbose logging on any feature, you would see a message similar to the following:
Logging settings: verbose - FALSE requestverbose - FALSE updateverbose - FALSE recordfilterperfverbose - FALSE merchverbose - FALSE textsearchrelrankverbose - FALSE textsearchspellverbose - FALSE dgraphperfverbose - FALSE dgraphrefinementgroupverbose - FALSE
