Pass Through HTTP Transport
Introduction
The Pass Through HTTP transport (PTHTTP transport) was developed by WSO2 as a more efficient and more scalable alternative to the standard Non-blocking HTTP transport (NHTTP transport) of Synapse. The PTHTTP transport was later contributed to the Synapse project, and was made the default HTTP transport of the Synapse ESB. All versions of Synapse released after version 2.1, use the PTHTTP transport by default to receive and send HTTP messages.
The PTHTTP transport was originally designed to facilitate content agnostic (pass through) HTTP mediation in a highly efficient manner. That is, it mediates HTTP messages without reading the message body. A number of enterprise integration scenarios (e.g. header-based routing, load balancing, URL rewriting) require efficient means of content agnostic mediation, and the standard NHTTP transport of Synapse is somewhat inefficient when supporting such use cases. The dual-buffer I/O model of the NHTTP transport induces unnecessary copying of message payload data between buffers, and it by default parses all received messages using the Axis2 message builder framework. The PTHTTP transport was originally designed with a single-buffer I/O model, and it skips the Axis2 message builder framework altogether. Therefore, the PTHTTP transport delivers excellent throughput and minimal latency when it comes to content agnostic mediation scenarios.
However, the original PTHTTP transport did not support any mediation scenario that requires accessing message payload data (e.g. content-based routing, XSLT transformation). In order to overcome this limitation, a number of architectural improvements were introduced to the Synapse mediation engine. These enhancements enable Synapse to use the PTHTTP transport as the default HTTP transport. Now Synapse uses a single buffer and does not invoke the Axis2 builders for all content agnostic mediation flows, but for content-aware mediation flows, it transparently falls back to the dual-buffer mode and engages the Axis2 message builder framework. Individual mediators in a message flow (sequence, proxy service) decide whether to invoke the Axis2 message builders or not, based on how the mediators intend to process the messages. This last enhancement, called deferred building, improves the mediation performance of non-HTTP flows as well.
Similar to the NHTTP transport, the PTHTTP transport is also based on the Apache HTTP Core NIO library. This library is based on the reactor pattern, and the PTHTTP transport uses two separate reactor instances:
- Listening I/O reactor: Handles network interactions between client applications and Synapse.
- Connecting I/O reactor: Handles network interactions between Synapse and the backend services.
Transport Configuration
Pass Through HTTP transport is configured by default in the SYNAPSE_HOME/repository/conf/axis2.xml file of Synapse. The default configuration activates the following four components:
- HTTP transport listener
- HTTP transport sender
- HTTPS transport listener
- HTTPS transport sender
Each of the above components are configured separately in the axis2.xml file. Next few sections describe the various parameters that can be used to customize the behavior of these components.
HTTP Transport Listener
The default configuration of the Pass Through HTTP listener is shown below, as it appears in the axis2.xml file.
The default configuration, simply sets the HTTP port to 8280 and specifies the name of the class responsible for processing incoming HTTP GET requests. A complete listing of supported parameters is given below.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| port |
The port number on which the HTTP listener should listen.
<parameter name="port">8280</parameter>
|
Yes | N/A |
| bind-address |
The hostname or IP address to which the HTTP listener should bind. When
deploying Synapse on machines that have multiple network interfaces,
this parameter can be used to bind the HTTP listener to a specific network
interface.
<parameter name="bind-address">10.0.0.5</parameter>
|
No | All available network interfaces |
| hostname |
The hostname or IP address used to calculate the service endpoints
exposed through this transport listener. This can be used to customize
the hostname of the endpoints (EPRs) that appear in the generated WSDLs.
This parameter is ignored if the WSDLEPRPrefix parameter is set.
<parameter name="hostname">10.0.0.5</parameter>
|
No | localhost |
| WSDLEPRPrefix |
A URL prefix that should be added to all the HTTP endpoints exposed
through this transport listener. This prefix will appear in all WSDLs
advertised by the transport. This is particularly useful when Synapse
is fronted by a proxy server or a load balancer and it is required to mention
the proxy/load balancer endpoints in the WSDLs generated by Synapse. This
parameter has higher priority than the hostname parameter.
<parameter name="WSDLEPRPrefix">http://proxy.example.com:8080/</parameter>
|
No | http://<host>:<port>/ |
| httpGetProcessor |
The full qualified name of the class that's responsible for handling incoming
HTTP GET requests. The specified class must implement the
org.apache.synapse.transport.passthru.HttpGetRequestProcessor interface. If it
is required to customize the way Synapse handles HTTP GET requests, one could
implement the above interface, and register the custom class with Synapse using
this parameter. By default Synapse ships with an HTTP GET request handler that
responds to ?wsdl and ?xsd requests and mediates all the others.
<parameter name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter>
|
No | N/A |
All the above parameters are also applicable to the HTTPS transport listener.
HTTP Transport Sender
The default Pass Through HTTP sender configuration available in the axis2.xml file is shown below.
Following parameters can be specified to customize the behavior of the HTTP sender.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| http.proxyHost |
The hostname or IP address of the proxy server through which the HTTP
messages should be sent. Use this property when Synapse should use an
external HTTP proxy to tunnel the outgoing HTTP traffic. This parameter
is only applicable to the HTTP sender. HTTPS sender does not support
external proxies yet.
<parameter name="http.proxyHost">proxy.example.com</parameter>
|
No | N/A |
| http.proxyPort |
The port number of the proxy server through which the HTTP messages
should be sent. Only used if the http.proxyHost parameter is also
configured. This parameter is only applicable to the HTTP sender.
HTTPS sender does not support external proxies yet.
<parameter name="http.proxyPort">8080</parameter>
|
No | 80 |
| http.nonProxyHosts |
Use this parameter to specify a proxy bypass list. That is, a list of
target hosts for which Synapse will not use the configured external
proxy. Only used if the http.proxyHost parameter is also set. The value
of this parameter can be a single hostname/IP address or a list of
hostnames/IP addresses separated by the '|' character. Parameter also
supports regular expressions which can be used to specify hostname
patterns.
<parameter name="http.nonProxyHosts">10.0.0.8|foo.com|*.bar.org</parameter>
|
No | N/A |
HTTPS Transport Listener
Pass Through HTTPS listener supports all the parameters supported by the HTTP listener. In addition, HTTPS listener supports several SSL/TLS specific parameters. The default HTTPS listener configuration in the axis2.xml file is shown below.
A complete list of parameters supported by the HTTPS listener is given below. Information regarding the parameters also supported by the HTTP listener are duplicated here for reader's convenience.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| port |
The port number on which the HTTPS listener should listen.
<parameter name="port">8243</parameter>
|
Yes | N/A |
| keystore |
Specifies the keystore that should be used to initialize SSL/TLS
support. A keystore typically houses a private key and some certificates
with their corresponding public keys. The value of this parameter is a
complex XML element. This XML element should specify:
Synapse ships with a default keystore file. It is highly recommended that a different keystore file is used in production deployments of Synapse, since the passwords of the default keystore are publicly known. <parameter name="keystore" locked="false">
<KeyStore>
<Location>lib/identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
|
No | N/A |
| truststore |
Specifies the truststore that should be used to initialize SSL/TLS
support. A truststore typically houses the CA certificates and other
trusted public certificates. The value of this parameter is a complex
XML element. This XML element should specify:
Synapse ships with a default truststore file. It is highly recommended that a different truststore file is used in production deployments of Synapse, since the password of the default truststore is publicly known. <parameter name="truststore" locked="false">
<TrustStore>
<Location>lib/trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>
|
No | N/A |
| SSLVerifyClient |
Use this parameter to enable client certificate verification (client
authentication). This option provides functionality similar to the
SSLVerifyClient directive
of Apache HTTPD. Supported values are:
<parameter name="SSLVerifyClient">require</parameter>
|
No | None |
| bind-address |
The hostname or IP address to which the HTTP listener should bind. When
deploying Synapse on machines that have multiple network interfaces,
this parameter can be used to bind the HTTP listener to a specific network
interface.
<parameter name="bind-address">10.0.0.5</parameter>
|
No | All available network interfaces |
| hostname |
The hostname or IP address used to calculate the service endpoints
exposed through this transport listener. This can be used to customize
the hostname of the endpoints (EPRs) that appear in the generated WSDLs.
This parameter is ignored if the WSDLEPRPrefix parameter is set.
<parameter name="hostname">10.0.0.5</parameter>
|
No | localhost |
| httpGetProcessor |
The full qualified name of the class that's responsible for handling incoming
HTTP GET requests. The specified class must implement the
org.apache.synapse.transport.passthru.HttpGetRequestProcessor interface. If it
is required to customize the way Synapse handles HTTP GET requests, one could
implement the above interface, and register the custom class with Synapse using
this parameter. By default Synapse ships with an HTTP GET request handler that
responds to ?wsdl and ?xsd requests and mediates all the others.
<parameter name="httpGetProcessor">foo.bar.CustomGETProcessor</parameter>
|
No | N/A |
| WSDLEPRPrefix |
A URL prefix that should be added to all the HTTP endpoints exposed
through this transport listener. This prefix will appear in all WSDLs
advertised by the transport. This is particularly useful when Synapse
is fronted by a proxy server or a load balancer and it is required to mention
the proxy/load balancer endpoints in the WSDLs generated by Synapse. This
parameter has higher priority than the hostname parameter.
<parameter name="WSDLEPRPrefix">https://proxy.example.com:8443/</parameter>
|
No | https://<host>:<port>/ |
HTTPS Transport Sender
As of today, the Pass Through HTTPS sender does not support sending messages through an external proxy. Therefore some of the parameters supported by the HTTP sender (http.proxyHost, http.proxyPort etc.) cannot be used with the HTTPS sender. However, there are several SSL/TLS related parameters that need to be configured when setting up the HTTPS sender. The default HTTPS sender configuration in the axis2.xml file is shown below.
Following table lists all the parameters supported by the Pass Through HTTPS sender.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| keystore |
Specifies the keystore that should be used to initialize SSL/TLS
support. A keystore typically houses a private key and some certificates
with their corresponding public keys. The value of this parameter is a
complex XML element. This XML element should specify:
Synapse ships with a default keystore file. It is highly recommended that a different keystore file is used in production deployments of Synapse, since the passwords of the default keystore are publicly known. <parameter name="keystore" locked="false">
<KeyStore>
<Location>lib/identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
|
No | N/A |
| truststore |
Specifies the truststore that should be used to initialize SSL/TLS
support. A truststore typically houses the CA certificates and other
trusted public certificates. The value of this parameter is a complex
XML element. This XML element should specify:
Synapse ships with a default truststore file. It is highly recommended that a different truststore file is used in production deployments of Synapse, since the password of the default truststore is publicly known. <parameter name="truststore" locked="false">
<TrustStore>
<Location>lib/trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>
|
No | N/A |
| HostnameVerifier |
This parameter can be used to configure target hostname verification.
That is, it enables validating server hostnames against the names specified
in the certificates presented by the servers during SSL handshake.
Supported values are:
<parameter name="HostnameVerifier">Strict</parameter>
|
No | Default |
| novalidatecert |
Use this parameter to turn on/off server certificate validation. If set to
'true', the HTTPS sender will not attempt to validate the certificates
presented by the remote servers. This behavior, however, is not recommended
for production deployments due to the potential security risks. If the
truststore parameter is specified, the value of this parameter is ignored
altogether.
<parameter name="novalidatecert">true</parameter>
|
No | false |
| customSSLProfiles |
By default, the HTTPS sender uses the SSL settings configured under
keystore and truststore parameters to communicate with all remote
HTTPS endpoints. However, in some cases we may need to use different
SSL settings to communicate with different endpoints. The customSSLProfiles
parameter allows configuring separate keystores and truststores for
each destination server. The value of this parameter is a set of XML elements
(profile elements). Each profile element must be configured with the following
child elements:
<parameter name="customSSLProfiles">
<profile>
<servers>server1.example.com:443,server2.example.com:443</servers>
<KeyStore>
<Location>lib/identity1.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
<TrustStore>
<Location>lib/trust1.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</profile>
<profile>
<servers>server3.example.com:443</servers>
<KeyStore>
<Location>lib/identity2.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
<TrustStore>
<Location>lib/trust2.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</profile>
</parameter>
|
No | N/A |
| CertificateRevocationVerifier |
Enable revocation status validation of server certificates using
OCSP and
CRL. Simply uncommenting
this parameter under the HTTPS sender configuration will activate the
feature. Two LRU caches are used to cache CRLs and OCSP responses until
they are expired. Two child XML elements are used to configure the cache
behavior.
<parameter name="CertificateRevocationVerifier" locked="false">
<CacheSize>100</CacheSize>
<CacheDurationMins></CacheDurationMins>
</parameter>
|
No | N/A |
Advanced Settings and Performance Tuning
In addition to the basic parameters described in the previous section, the Pass Through HTTP transport provides some advanced options to tweak its runtime behavior and performance. These options should be configured in the SYNAPSE_HOME/lib/passthru-http.properties file. These advanced options enable the user to control some of the low-level transport settings related to TCP sockets, I/O buffers and thread pools. Following sections describe all the advanced options that can be set for the Pass Through HTTP transport.
Apache HTTP Core Settings
Following properties control various facets of Apache HTTP Core, the framework underlying the Pass Through HTTP transport.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| http.socket.timeout |
Sets the TCP socket timeout in milliseconds
(See SO_TIMEOUT).
This applies to sockets opened by both transport listener and sender.
http.socket.timeout=20000
|
No | 60000 |
| http.socket.timeout.listener |
Sets the timeout in milliseconds for all the TCP sockets opened by the
transport listener. This overrides the value of
http.socket.timeout for the transport
listener.
http.socket.timeout.listener=20000
|
No | Value of http.socket.timeout |
| http.socket.timeout.sender |
Sets the timeout in milliseconds for all the TCP sockets opened by the
transport sender. This overrides the value of
http.socket.timeout for the transport
sender.
http.socket.timeout.sender=20000
|
No | Value of http.socket.timeout |
| http.connection.timeout |
Sets the TCP connection timeout in milliseconds. This determines the timeout
value for non-blocking connection requests. Setting this property to
0 disables connection timeout (i.e. no timeout).
http.connection.timeout=30000
|
No | 0 |
| http.nio.interest-ops-queueing |
Determines whether or not I/O interest operations are to be queued and
executed asynchronously by the I/O reactor thread or to be applied to
the underlying
SelectionKey
immediately. Allowed values are either 'true' or 'false'.
http.nio.interest-ops-queueing=false
|
No | false |
| http.tcp.nodelay |
Setting this property to 'true' disables
Nagle's algorithm
for the HTTP connections. That is, outgoing data will not be buffered
and aggregated together
(See TCP_NODELAY).
http.tcp.nodelay=true
|
No | true |
| http.socket.buffer-size |
Sets the size of the I/O session buffers (in bytes) used by the transport
for reading incoming data and writing outgoing data.
http.socket.buffer-size=4096
|
No | 8192 |
| http.socket.rcv-buffer-size |
Sets the size of the buffers (in bytes) used by the underlying platform
for incoming network I/O. This value is only a hint. When set, this is a
suggestion to the OS kernel from Synapse about the size of buffers to
use for the data to be received over the socket
(See SO_RCVBUF).
If no value is specified, Synapse will use the platform (OS) default.
http.socket.rcv-buffer-size=8192
|
No | Platform default |
| http.socket.snd-buffer-size |
Sets the size of the buffers (in bytes) used by the underlying platform
for outgoing network I/O. This value is only a hint. When set, this is a
suggestion to the OS kernel from Synapse about the size of buffers to
use for the data to be sent over the socket
(See SO_SNDBUF).
If no value is specified, Synapse will use the platform (OS) default.
http.socket.snd-buffer-size=8192
|
No | Platform default |
| http.socket.linger |
Specifies the linger-on-close timeout duration (in milliseconds) for the
sockets created by the HTTP transport. Setting to 0 or a negative value
disables linger-on-close
(See SO_LINGER).
http.socket.linger=5000
|
No | -1 |
| http.socket.reuseaddr |
Sets the SO_REUSEADDR
socket option for the sockets created by the HTTP transport. Accepted
values are either 'true' or 'false'.
http.socket.reuseaddr=true
|
No | false |
| http.nio.select-interval |
Sets the time interval in milliseconds at which the I/O reactor wakes up
to check for timed out sessions and session requests.
http.nio.select-interval=2500
|
No | 1000 |
| io_threads_per_reactor |
Sets the number of I/O dispatcher threads to be used by each I/O reactor.
Typically, this property controls the ability of the HTTP transport
to handle concurrent I/O events.
It is recommended that this property is set to the number of CPU cores
available for Synapse. By default, Synapse determines the number of
available CPU cores and initializes this setting accordingly.
io_threads_per_reactor=4
|
No | Number of CPU cores |
| http.malformed.input.action |
Specifies the action to be performed when a malformed input is detected
during character set encoding or decoding. Supported values are
'ignore', 'replace' and 'report'. See CodingErrorAction
for more details on each of these options.
http.malformed.input.action=ignore
|
No | report |
| http.unmappable.input.action |
Specifies the action to be performed when an un-mappable character is detected
during character set encoding or decoding. Supported values are
'ignore', 'replace' and 'report'. See CodingErrorAction
for more details on each of these options.
http.malformed.input.action=ignore
|
No | report |
Synapse HTTP Mediation Settings
Following settings determine the behavior of Synapse with respect to mediating HTTP traffic.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| io_buffer_size |
Sets the size of the I/O buffers (in bytes) used as the pipes between HTTP
listener and sender. Typically, the HTTP listener would write the incoming
message data to one of these buffers, and the sender would read from it to
send the message out.
io_buffer_size=10240
|
No | 8192 |
| http.max.connection.per.target |
Determines the maximum number of HTTP connections the transport is
allowed to maintain per target HTTP host (i.e. host:port pair). Used to
control the number of connections created by the Pass Through transport
for each endpoint.
http.max.connection.per.target=1000
|
No | Integer.MAX_VALUE |
| http.user.agent.value |
Specifies the string that should be used as the value of the HTTP User-Agent
header for outgoing requests. If the request already has a User-Agent
header (sent by the client), and the
http.user.agent.preserve property
is set to true, this property will be ignored.
http.user.agent.value=Finance-Data-Client
|
No | Synapse-PT-HttpComponents-NIO |
| http.server.value |
Specifies the string that should be used as the value of the HTTP Server
header for outgoing responses. If the response already has a Server
header (sent by the backend server), and the
http.server.preserve property
is set to true, this property will be ignored.
http.server.value=Media-Gateway-Server
|
No | Synapse-PT-HttpComponents-NIO |
| http.user.agent.preserve |
Specifies whether Synapse should preserve the User-Agent header sent by the
client applications, when forwarding messages to backend servers. Allowed
values are either true or false. If set to false, Synapse will overwrite
the original User-Agent header value with the value of the
http.user.agent.value property.
http.user.agent.preserve=true
|
No | false |
| http.server.preserve |
Specifies whether Synapse should preserve the Server header sent by the
backend servers, when forwarding messages to client applications. Allowed
values are either true or false. If set to false, Synapse will overwrite
the original Server header value with the value of the
http.server.value property.
http.server.preserve=false
|
No | true |
Thread Pool Settings
The Pass Through HTTP transport uses a thread pool for mediating messages through the Synapse mediation engine. Both HTTP listener and sender draw threads from this pool. It is further shared between the HTTP and HTTPS transports. The size of this thread pool determines the capacity of Synapse to mediate concurrent HTTP messages.
| Parameter Name | Description/Example | Required | Default |
|---|---|---|---|
| worker_pool_size_core |
Set the core size of the thread pool used by the Pass Through HTTP
transport. The thread pool starts with 0 threads, and grows in size as
new tasks are submitted to it. Once the number of threads reaches or
exceeds the core size, the thread pool will not allow the thread count
to go below the core size. That is, the thread pool keeps the core amount
of threads in the pool even if they are idle.
worker_pool_size_core=100
|
No | 40 |
| worker_pool_size_max |
The thread pool used by the Pass Through HTTP transport grows in size, as
more and more tasks are submitted to it. This property determines the
maximum limit up to which the thread pool may grow. In other words,
this property specifies the maximum number of threads that may ever exist
in the transport thread pool. Value of this property must be greater than
or equal to the value of worker_pool_size_core.
worker_pool_size_max=500
|
No | 200 |
| worker_thread_keepalive_sec |
Specifies the idle time period (in seconds) for the excess threads in
the Pass Through transport thread pool. When the number of threads in the
pool is greater than worker_pool_size_core,
this is the maximum time that excess idle threads will wait for new tasks
before terminating.
worker_thread_keepalive_sec=10
|
No | 60 |
| worker_pool_queue_length |
Determines the length of the queue used by the Pass Through transport
thread pool to store pending jobs. To use an unbounded queue, set this
property to -1. If a bounded queue is used, and if the queue ever gets
filled to its capacity, any further attempts to submit jobs will fail,
causing some messages to be dropped by Synapse. The thread pool starts
queueing jobs, when all the existing threads are busy and the pool has
already reached the maximum number of threads.
worker_pool_queue_length=1000
|
No | -1 |
Guidelines for Using Advanced Settings
Note that all the above settings are optional. In fact the entire passthru-http.properties file is optional. Synapse is programmed with some reasonable default values for each of the above settings, and these defaults will deliver good performance in most scenarios. However, to obtain 'best' performance from the Pass Through HTTP transport, it is recommended to tweak the above values. At least, consider tuning the worker_pool_size_core and worker_pool_size_max to match the expected load in your deployment.
You might be tempted to configure the transport with a very large thread pool (e.g. 1000's of threads). But bare in mind that more threads equal more memory usage. Also, on some operating systems there are restrictions on the number of threads that can be spawned by an application. Therefore, do not attempt to set the thread pool size to an unnecessarily large value. Do a rough estimate of your expected workload (expected number of concurrent users), and set the thread pool size accordingly. As for setting the number of I/O dispatcher threads (io_threads_per_reactor), setting it to match the number of available CPU cores generally results in good performance. Synapse does this for you by default, so you shouldn't have to do any extra work with regard to this property.
It is highly recommended to run some load tests on Synapse using your own mediation configurations (sequences, proxy services etc.) on the actual production hardware. This will give you a much clear idea about what transport level properties need to be tuned up in your deployment.
Unix/Linux Specific Settings
Users deploying Synapse on Unix/Linux systems are further advised to set the following OS level configuration parameters. This is completely optional, but for high-throughput and high-volume deployments, configuring these parameters may prove to be useful.
-
Increase the limit on open file descriptors by editing the
/etc/security/limits.conf file.
* soft nofile 4096 * hard nofile 65535
-
Increase the TCP port range and optimize other TCP settings in the
/etc/sysctl.conf file.
net.ipv4.tcp_fin_timeout = 30 fs.file-max = 2097152 net.ipv4.tcp_tw_recycle = 1 net.ipv4.tcp_tw_reuse = 1 net.core.rmem_default = 524288 net.core.wmem_default = 524288 net.core.rmem_max = 67108864 net.core.wmem_max = 67108864 net.ipv4.tcp_rmem = 4096 87380 16777216 net.ipv4.tcp_wmem = 4096 65536 16777216 net.ipv4.ip_local_port_range = 1024 65535
Logging Configuration
Note: This section is applicable to both Pass Through and NHTTP transports of Synapse.
Synapse HTTP transports have some advanced logging capabilities built in to them, which can be enabled to obtain more low-level information about how the transports operate. These logging features are based on Apache Commons Logging and Log4J, which constitute the logging framework used by Apache Synapse. Therefore, these features should be enabled from the SYNAPSE_HOME/lib/log4j.properties file of the installation.
Advanced logging for HTTP transports is activated by setting the log level to DEBUG on a set of predefined logging categories. These categories are already listed in the default log4j.properties file that ships with Synapse, and you only need to uncomment them to use the advanced logging features. Please note that changes to log4j.properties file are not picked up at runtime, and therefore you must restart Synapse for the changes to take effect. A complete listing of the logging categories related to Synapse HTTP transports is given below.
- log4j.category.org.apache.synapse.transport.http.headers=DEBUG
- Enables logging the headers of all the HTTP messages received and sent by Synapse.
- log4j.category.org.apache.synapse.transport.http.headers.SourceHeaders=DEBUG
- Enables logging the headers of all the HTTP messages exchanged between client applications and Synapse.
- log4j.category.org.apache.synapse.transport.http.headers.TargetHeaders=DEBUG
- Enables logging the headers of all the HTTP messages exchanged between Synapse and backend servers.
- log4j.category.org.apache.synapse.transport.http.wire=DEBUG
- Enables logging the complete wire-level messages received and sent by Synapse. This will log HTTP headers as well message bodies.
- log4j.category.org.apache.synapse.transport.http.wire.SourceWire=DEBUG
- Enables logging the complete wire-level messages exchanged between client applications and Synapse.
- log4j.category.org.apache.synapse.transport.http.wire.TargetWire=DEBUG
- Enables logging the complete wire-level messages exchanged between Synapse and backend servers.
- log4j.category.org.apache.synapse.transport.http.conn=DEBUG
- Enables logging for all HTTP connections. This will log all the significant events that occur on HTTP connections during their life cycles. Some of these events include read, write and shutdown.
- log4j.category.org.apache.synapse.transport.http.conn.SourceConnection=DEBUG
- Enables logging for HTTP connections established between client applications and Synapse.
- log4j.category.org.apache.synapse.transport.http.conn.TargetConnection=DEBUG
- Enables logging for HTTP connections established between Synapse and backend servers.
- log4j.category.org.apache.synapse.transport.http.session=DEBUG
- Enables logging for all I/O sessions. This will log all the significant events that occur on HTTP I/O sessions during their life cycles. Some of these events include setting NIO interest ops, read, write and shutdown.
- log4j.category.org.apache.synapse.transport.http.session.SourceSession=DEBUG
- Enables logging for I/O sessions established between client applications and Synapse.
- log4j.category.org.apache.synapse.transport.http.session.TargetSession=DEBUG
- Enables logging for I/O sessions established between Synapse and backend servers.
- log4j.category.org.apache.synapse.transport.http=DEBUG
- Enables all the advanced logging features (all listed above).
Guidelines for Using Advanced Logging
Most of the above advanced logging features have been designed to aid Synapse developers in identifying problems and fixing issues in the Synapse HTTP transports. However, they are also useful to the Synapse users and system administrators when debugging configuration errors and certain types of integration problems. For instance, if you ever come across a situation where Synapse behaves erratically when communicating with a particular client or a server, enabling some of the above mentioned logging features may help you pinpoint the cause of the issue.
Please bare in mind that you trade mediation performance for additional logging. As you enable more and more logging features, the performance degradation induced by logging becomes greater. Hence these advanced logging features are not suitable to be enabled on production deployments. However, they are quite helpful during the development and testing phases of an integration project. In a production deployment, you may occasionally need to enable advanced logging for short periods of time to obtain debug information to resolve certain production issues. But it is not recommended to have these features permanently enabled on production systems.
Also note that activating advanced logging features may greatly increase the amount of data written to the Synapse log files. If the Synapse server is receiving a large volume of traffic, enabling any one of the above logging features may cause Synapse to generate gigabytes of logs within minutes. This could easily drive a system out of disk space or cause some other unexpected I/O issue. Therefore be mindful about how much extra information you want Synapse to log, the prevailing levels of load/traffic and the availability of hardware resources.
Monitoring with JMX
Pass Through HTTP transport exposes several JMX MBeans, which can be used to obtain crucial statistical information about how the transport performs. This includes the number of inbound and outbound connections opened by the transport, the number of HTTP messages mediated, distribution of the message sizes and the latency incurred by Synapse when forwarding HTTP traffic. Following sections describe the available JMX MBeans and the attributes present in each MBean.
ConnectionsView (org.apache.synapse.PassThroughConnections)
Typically, Synapse exposes four instances of this MBean, under the following identifiers.
- http-listener: Provides information regarding the connections established between the client applications and the Pass Through HTTP listener.
- http-sender: Provides information regarding the connections established between the Pass Through HTTP sender and the backend servers.
- https-listener: Provides information regarding the connections established between the client applications and the Pass Through HTTPS listener.
- https-sender: Provides information regarding the connections established between the Pass Through HTTPS sender and the backend servers.
Each instance of the MBean consists of the following attributes.
| Attribute | Data Type | Description |
|---|---|---|
| ActiveConnections | int | Number of currently active (open) connections |
| LastMinuteConnections | int | Number of connections created during last minute (updated every minute) |
| Last5MinuteConnections | int | Number of connections created during last 5 minutes (updated every minute) |
| Last15MinuteConnections | int | Number of connections created during last 15 minutes (updated every minute) |
| LastHourConnections | int | Number of connections created during last hour (updated every 5 minutes) |
| Last8HourConnections | int | Number of connections created during last 8 hours (updated every 5 minutes) |
| Last24HourConnections | int | Number of connections created during last 24 hours (updated every 5 minutes) |
| RequestSizeMap | java.util.Map |
A map representing the size distribution of the request messages
processed by the transport. Map keys are strings and the values are
integers. Following keys are available by default.
|
| ResponseSizeMap | java.util.Map |
A map representing the size distribution of the response messages
processed by the transport. Map keys are strings and the values are
integers. Following keys are available by default.
|
| LastResetTime | java.util.Date | The MBean statistics can be reset manually via one of the operations provided in the MBean interface. This attribute keeps track of the date and time of the last reset event. If the MBean has never been reset, this attribute provides the time when the transport was started. |
LatencyView (org.apache.synapse.PassThroughTransportLatency)
Synapse keeps track of how much latency (delay) is added by the ESB to each message flow. This is an estimate of how much time a client application would save if the requests were to go directly to the backend server, instead of going through Synapse. The LatencyView MBean exposes this information via JMX. Synapse usually exposes two instances of this MBean, one for the HTTP transport and the other for the HTTPS transport. Each instance consists of the following attributes.
| Attribute | Data Type | Description |
|---|---|---|
| AllTimeAvgLatency | double | Average latency in milliseconds, computed over all the messages mediated by the transport |
| LastMinuteAvgLatency | double | Average latency in milliseconds, computed over the messages mediated by the transport during last minute (updated every minute) |
| Last5MinuteAvgLatency | double | Average latency in milliseconds, computed over the messages mediated by the transport during last 5 minutes (updated every minute) |
| Last15MinuteAvgLatency | double | Average latency in milliseconds, computed over the messages mediated by the transport during last 15 minutes (updated every minute) |
| LastHourAvgLatency | double | Average latency in milliseconds, computed over the messages mediated by the transport during last hour (updated every 5 minutes) |
| Last8HourAvgLatency | double | Average latency in milliseconds, computed over the messages mediated by the transport during last 8 hours (updated every 5 minutes) |
| Last24HourAvgLatency | double | Average latency in milliseconds, computed over the messages mediated by the transport during last 24 hours (updated every 5 minutes) |
| LastResetTime | java.util.Date | The MBean statistics can be reset manually via one of the operations provided in the MBean interface. This attribute keeps track of the date and time of the last reset event. If the MBean has never been reset, this attribute provides the time when the transport was started. |
TransportView (org.apache.synapse.Transport)
An instance of this MBean is usually available for each transport listener and sender enabled in Synapse. This also includes non-HTTP transports. As far as the Pass Through HTTP transport is concerned, Synapse exposes four instances of this MBean with the following identifiers.
- passthru-http-receiver
- passthru-http-sender
- passthru-https-receiver
- passthru-https-sender
Following attributes are available on each instance of the MBean.
| Attribute | Data Type | Description |
|---|---|---|
| ActiveThreadCount | int | The number of threads in the transport thread pool, that are currently executing tasks |
| AvgSizeReceived | double | Average size (in bytes) of all the messages received |
| AvgSizeSent | int | Average size (in bytes) of all the messages sent |
| BytesReceived | long | The total number of bytes received by the transport |
| BytesSent | long | The total number of bytes sent by the transport |
| FaultsReceiving | long | The total number of errors encountered while receiving messages |
| FaultsSent | long | The total number of errors encountered while sending messages |
| LastResetTime | long | The MBean statistics can be reset manually via one of the operations provided in the MBean interface. This attribute keeps track of the timestamp (milliseconds since epoch) of the last reset event. If the MBean has never been reset, this attribute provides the time when the transport was started. |
| MaxSizeReceived | long | Size of the largest message received (in bytes) |
| MaxSizeSent | long | Size of the largest message sent (int bytes) |
| MessagesReceived | long | Total number of messages received |
| MessagesSent | long | Total number of messages sent |
| MetricsWindow | long | Time elapsed in milliseconds, since the last MBean reset event |
| MinSizeReceived | long | Size of the smallest message received (in bytes) |
| MinSizeSent | long | Size of the smallest message sent (int bytes) |
| QueueSize | long | Number of tasks currently queued on the transport thread pool |
| ResponseCodeTable | java.util.Map | A map representing the distribution of HTTP status codes received by the transport. Keys are integers (status codes) and the values are long integers indicating the number of time each status code was encountered. |
| TimeoutsReceiving | long | Number of timeouts encountered while receiving messages |
| TimeoutsSending | long | Number of timeouts encountered while sending messages |