Fault Injection

The Fault Injection feature is an API that intentionally generates failures in order to verify the system’s stability and error-handling capability. With it, you can induce initialization failures, frame processing failures, and delays for decoder, filter, and encoder that use a specific module, and you can run tests by creating an environment similar to real failure scenarios.

Enabling Fault Injection

You can configure Fault Injection in Server.xml under <Server><Module> as follows:

<Server>
    ...
    <Modules>
        ...
        <FaultInject>
            <Enable>true</Enable>
        </FaultInject>
        ...
    </Modules>
    ...
</Server>

API Interface

Configuring Fault Injection

You can configure Fault Injection as an array under transcoder. When you apply a new configuration, all existing settings are cleared. Likewise, when OvenMediaEngine is restarted, all related settings are reset to their initial state.

Request

POST /v2/internals/tests:setFaultInject

Header

Authorization: Basic {credentials}

# Authorization
Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "transcoder" : [
      { 
         "targetModule" : "default",
         "targetDeviceId" : 0,
         "targetComponent" : "decoder",
         "faultType" : "initFailed",
         "faultRate" : 50
      },        
      { 
         "targetModule" : "openh264",
         "targetDeviceId" : 0,
         "targetComponent" : "filter",
         "faultType" : "processFailed",
         "faultRate" : 2.0
       },    
      { 
         "targetModule" : "nv",
         "targetDeviceId" : 0,
         "targetComponent" : "encoder",
         "faultType" : "lagging",
         "faultRate" : 10.0
       },
      { 
         "targetModule" : "default",
         "targetDeviceId" : 0,
         "targetComponent" : "decoder",
         "faultType" : "processFailed",
         "faultRate" : 2.0
       }
   ]
}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}

400 Bad Request

Fault injection module is not enabled in the server configuration

400 Bad Request

Invalid request

Parameter	Input Range	Description
targetModule	Codec Module	Specifies the module that will be targeted by Fault Injection. default, openh264, x264, libvpx, nv, xma. Please refer to the name value in v2/internals/codecs.
targetDeviceId	0~ (Device ID)	Specifies the ID assigned to the target module for Fault Injection. Please refer to the id value in v2/internals/codecs.
targetComponent	decoder, encoder, filter	Specifies the component type of the target module for Fault Injection.
faultType	initFailed, processFailed, lagging	Specifies the type of fault testing to perform. initFailed: Reproduces a module initialization failure. processFailed: Reproduces failures in decoding, filtering, or encoding. lagging: Reproduces a processing delay (300ms).
faultRate	0.01~100.0	Specifies the probability (%) that fault testing will occur.

Disabling Fault Injection

If you do not specify values in the transcoder array, all related settings are disabled.

Request

POST /v2/internals/tests:setFaultInject

Header

Authorization: Basic {credentials}

# Authorization
Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "transcoder" : [ ]
}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}