General

All logs are housed in their respective Docker containers, you can see individual logs per container by executing docker ps to get the container id for your desired container, and then docker logs <container-id> to view the logs in that container.


Healthcheck Endpoint:

The Narrative Generation API has a healthcheck endpoint that returns the health of the service. When you send a request to this endpoint, you should receive the specified success response (see below). If you do not receive this success response, that means that the Narrative Generation API is down. 

cURL request:

curl https://localhost

Note: This is the command as executed on the machine. To execute the command from a local machine to ping the load balancer, you should use the name of the load balancer.

Success Response:

{"name":"@narrativescience/viz-server","version":"1.0.120"}

Full Request Check:

Alternatively, if you’d like to make a full request, this accomplishes the same thing. Instead of the success response however, you will receive a narrative response. 

cURL request:


curl --request POST --url 'https://[hostname_url]/v2/stories/linechart?user_key=779c1feefe19437dd4b22672fa2b6072' --header 'content-type: text/plain' --data '{"metadata":{"platform":"TEST"},"api_version":2,"data":{"dimensions":[{"name":"YearMonth","id":"jSbKfT","labels":[{"singular":"period","plural":"periods"}]}],"measures":[{"id":"UKMDBPJ","outside":false,"up_sentiment":"good","format":"number","format_options":{"decimal_separator":".","thousands_separator":",","decimal_places":"3"},"name":"revenue"}],"rows":[[{"id":13,"value":"Jan-06"},{"value":4471954.159999999,"id":0}],[{"id":11,"value":"Feb-06"},{"value":4891823.610000007,"id":0}],[{"id":12,"value":"Mar-06"},{"value":4485061.010000004,"id":0}],[{"id":15,"value":"Apr-06"},{"value":3295110.9099999983,"id":0}],[{"id":16,"value":"May-06"},{"value":3498681.6499999985,"id":0}],[{"id":7,"value":"Jun-06"},{"value":4649029.440000005,"id":0}],[{"id":10,"value":"Jul-06"},{"value":3098673.9399999934,"id":0}],[{"id":6,"value":"Aug-06"},{"value":5013458.460000009,"id":0}],[{"id":4,"value":"Sep-06"},{"value":4677429.150000008,"id":0}],[{"id":8,"value":"Oct-06"},{"value":4973125.090000011,"id":0}],[{"id":5,"value":"Nov-06"},{"value":4863249.53000001,"id":0}],[{"id":14,"value":"Dec-06"},{"value":4630509.530000005,"id":0}],[{"id":2,"value":"Jan-07"},{"value":3745465.06,"id":0}],[{"id":17,"value":"Feb-07"},{"value":3746215.4500000016,"id":0}],[{"id":23,"value":"Mar-07"},{"value":3665362.6599999974,"id":0}],[{"id":0,"value":"Apr-07"},{"value":3261139.04,"id":0}],[{"id":18,"value":"May-07"},{"value":3850703.370000012,"id":0}],[{"id":1,"value":"Jun-07"},{"value":4245207.7399999965,"id":0}],[{"id":21,"value":"Jul-07"},{"value":3792904.29,"id":0}],[{"id":19,"value":"Aug-07"},{"value":3816579.490000002,"id":0}],[{"id":3,"value":"Sep-07"},{"value":4320195.759999997,"id":0}],[{"id":22,"value":"Oct-07"},{"value":4912291.189999999,"id":0}],[{"id":20,"value":"Nov-07"},{"value":3903059.1099999957,"id":0}],[{"id":9,"value":"Dec-07"},{"value":2865437.539999993,"id":0}]]},"configuration":{"authoring":{"verbosity":"high"},"analytics":{"trendline":{"enabled":true,"index":0,"thresholds":{"inclusion":{"value":0.95}}},"segments":{"enabled":true,"index":0}}}}'

Success Response:

The success response will look like some variation of this:


<section class="ns-narrative"><section class="ns-section" data-section-id="intro"><div class="ns-section-title"><span class="sentence">This analysis measures revenue by YearMonth. </span></div><div class="ns-section-content"><ul class="ns-content-container ns-bullets"><li data-content-id="series-total"><span class="sentence">Total revenue was <span class="number">98.7 million</span> across all <span class="number">24</span> <span data-dimension-id="jSbKfT" data-tense="plural" class="entity-label">periods</span>. </span></li><li data-content-id="min-max"><span class="sentence">Values ranged from <span class="number">2.9 million</span> (Dec-07) to <span class="number">5 million</span> (Aug-06). </span></li><li data-content-id="series-movement-only"><span class="sentence">Revenue fell by <span class="percent">36%</span> over the course of the series from <span class="number">4.5 million</span> to <span class="number">2.9 million</span> and ended on a bad note, decreasing by <span class="number">2 million</span> from Oct-07 to Dec-07. </span></li><li data-content-id="best-change"><span class="sentence">The largest single decline occurred in Jul-06 (-<span class="percent">33%</span>). </span></li><li data-content-id="series-counter-movement"><span class="sentence">The largest single increase immediately followed the biggest single decrease, when it rose <span class="percent">62%</span> from <span class="number">3.1 million</span> to <span class="number">5 million</span> in Aug-06. </span></li><li data-content-id="positive-runs-streak"><span class="sentence">Revenue showed the longest span of consistent improvement over <span class="number">three</span> <span data-dimension-id="jSbKfT" data-tense="plural" class="entity-label">periods</span> from Jul-07 to Oct-07, <span class="highlight" data-analytic-id="segments" data-sentiment="good">increasing by <span class="percent">30%</span></span>. </span></li><li data-content-id="negative-runs-streak"><span class="sentence">The largest net decline was from Aug-06 to Dec-07, when revenue <span class="highlight" data-analytic-id="segments" data-sentiment="bad">decreased by <span class="number">2.1 million</span> (<span class="percent">43%</span>)</span>. </span><span class="sentence">The <span class="number">three</span> <span data-dimension-id="jSbKfT" data-tense="plural" class="entity-label">periods</span> of consecutive decline from Oct-06 to Jan-07 when revenue <span class="highlight" data-analytic-id="segments" data-sentiment="bad">fell by <span class="percent">25%</span> significantly impacted this net decline</span>. </span></li><li data-content-id="opposite-direction"><span class="sentence">Revenue fluctuated over the course of the series with <span class="percent">59%</span> of data points moving in an opposite direction from the previous point. </span></li></ul></div></section></section>%

 

Explanation of Services and Log Locations:

In order to set up monitoring, we recommend monitoring the following two services. Monitoring any other services would be redundant since other services are dependent on these two services:

  • viz-server
  • viz-proxy-service
  1. Service Name: viz-proxy-service
      1. Description:
        1. Nginx service that listens on port 443 for incoming requests from the Tableau Dashboard and will route requests to proper microservices
        2. Web proxy used for SSL termination

 

  • Note: We will need to make an update to the installer for the access logs to appear in this location. Once we make the update, we expect the logs to appear here. Currently, only the error logs appear

 

  1. Service Name: viz-extension-server
    1. Node.js service that provides static javascript to drive Narratives for Tableau configuration experience
    2. When a user first uses Narratives for Tableau, the .trex extension will make a call to the server where Narratives for Tableau is installed
  2. Service Name: viz-server
    1. Description: Node.js service that is the language generation engine that produces content in plain English explanations
  3. Service Name: ns_viz_analytics
    1. Python service that performs computations on data extracted from a Tableau Dashboard
    2. Passes results of computations to the Storywriting service to insert into plain English explanations


API Response and Error Codes

 

  • 200: Success
  • 4XX: Client error. Occurs when certain requirements for Narrative Generation are not met. These errors occur due to misconfigured data payload and must be fixed by Narrative Science since the Narratives for Tableau Extension performs data payload transformations
  • 5XX: Server error. occurs during case of unhandled errors during processing. If this error occurs, please email Narrative Science with the full details of the API request.