#
# Cumulative Field Sum
#
# This snapon is used to compute the sum of a cumulative field.  For instance, Flash logs log the bandwidth-so-far-this-session for each event, so to compute the total bandwidth
# for an event, it is necessary to subtract the bandwidth of the current event, from the bandwidth of the previous event in the session.  This snapon can be used
# to compute the actual bandwidth per event for Flash, or similar.
#


cumulative_field_sum = {

  version = "1.2"

  # 2012-??-?? - GMF - 1.0 - Initial creation
  # 2012-03-01 - GMF - 1.1 - Added support for handling reused "session id" values
  # 2012-03-04 - GMF - 1.1.1 - Removed semicolon after version
  # 2013-03-20 - GMF - 1.2 - Implemented using collect/accept, for lower memory usage and automatic garbage collection of old values
  # 2013-05-06 - GMF - 1.2.1 - Added loadorder sort, to correctly order out-of-order events within a single session.
 
  label = "$lang_admin.snapons.cumulative_field_sum.label"
  comment = "$lang_admin.snapons.cumulative_field_sum.comment"
  config_snapon_category = ""

  parameters = {
  

    date_time_field = {
    
      parameter_value = "date_time"
      
      validation_type = "string"
      
      form_element_label = "$lang_admin.snapons.cumulative_field_sum.parameters.date_time_field.form_element_label"
      form_element_type = "select"
      select_options_source = "database_fields"
      
      description = ""
    
    } # date_time_field
 

    cumulative_field = {
      
      parameter_value = "cs_bytes"
      
      validation_type = "string"
      
      form_element_label = "$lang_admin.snapons.cumulative_field_sum.parameters.cumulative_field.form_element_label"
      form_element_type = "select"
      select_options_source = "database_fields"
      
      description = ""
      
    } # cumulative_field


    # This is the field which has a different value in the log data, for each session
    session_id_field = {
      
      parameter_value = "session_id"
      
      validation_type = "string"
      
      form_element_label = "$lang_admin.snapons.cumulative_field_sum.parameters.session_id.form_element_label"
      form_element_type = "select"
      select_options_source = "database_fields"
      
      description = ""
      
    } # session_id_field

    cumulative_field_sum_name = {
    
      parameter_value = "$lang_admin.snapons.cumulative_field_sum.parameters.cumulative_field_sum_name.parameter_value"
      final_node_name = ""
      
      validation_type = "field_label"
      validate_field_label_for = {
        database_fields = true
        report_fields = true
      }
      
      form_element_label = "$lang_admin.snapons.cumulative_field_sum.parameters.cumulative_field_sum_name.form_element_label"
      form_element_type = "text"
      form_element_width = "380"
      
      description = ""
    
    } #  cumulative_field_sum_name

    display_format_type = {

      parameter_value = "integer"

      validation_type = "string"
      form_element_label = "$lang_admin.snapons.aggregating_field.parameters.display_format_type.form_element_label"
      form_element_type = "select"

      select_options_source = "custom_fields"

      select_options = {

        integer = {

          option_value = "integer"
          label = "$lang_admin.snapons.aggregating_field.display_format_type.integer"

        } # integer

        bandwidth = {

          option_value = "bandwidth"
          label = "$lang_admin.snapons.aggregating_field.display_format_type.bandwidth"

        } # bandwidth

        duration_compact = {

          option_value = "duration_compact"
          label = "$lang_admin.snapons.aggregating_field.display_format_type.duration_compact"

        } # duration_compact

      } # select_options

      description = "$lang_admin.snapons.aggregating_field.parameters.display_format_type.description"

    } # display_format_type
      
  } # parameters
  
  parameters_form = {

    group_1 = {
      description = "$lang_admin.snapons.cumulative_field_sum.parameters_form.group_1.description"
      parameters = {
        date_time_field = true
        cumulative_field = true
        session_id_field = true
        cumulative_field_sum_name = true
        display_format_type = true
      } # parameters
    } # group 1
    
  } # parameters_form
  
  
  attach_operations = {

    # When attaching: Add the cumulative field sum database field
    add_database_field = {
      type = "add_database_fields"
      fields = {

        "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}" = {

          label = "{= @parameters{'cumulative_field_sum_name'}{'parameter_value'} =}"
          type = "int"
          derivation_method = "database_filter"
          aggregation_method = "sum"
          category = ""
          index = "true"
          suppress_top = "0"
          suppress_bottom = "2"
          integer_bits = "64"

        } # cumulative_field_sum_name
  
      } # fields

    } # add_database_field

    # When attaching: add the database filter to calculate the field
    add_database_filter = {

      type = "add_database_filters"

      filters = {

        "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}" = {
  
          conditions = {
  
            # Sort chronologically
            sort = {
              type = "sort"
              fields = {
                date_time = {
                  column_name = "{= @parameters{'date_time_field'}{'parameter_value'} =}"
                }

		# 2013-05-06 - GMF - Also sort by loadorder, to make the stort stable within each second of log data.  Otherwise, entries may be scrambled within a second, resulting in out-of-order increasing field values, which causes the sum to be "restarted".  This was commented out--why? If it's a problem, sorting on the numerical field itself might work too.
                loadorder = {
                  column_name = "loadorder"
                }
              } # fields
            } # sort
 
	# 2013-03-20 - GMF - Switched to use accept/collect 
            # This node keeps the previous value of all sessions
#            previous_value = {
#              type = "variable"
#              variable_name = "previous_value"
#              variable_type = "node"
#              initial_value = ""
#            } # previous_value

          } # conditions

          # The follow expression is the code which implements the filter action  
          expression = `

# 2013-02-08 - GMF - If the field value is zero, don't subtract past values from it.  E.g., wowza uses "-" on disconnect for sc-stream-bytes, but that doesn't mean we should have a negative value for the cumulative field.
if (({= @parameters{'cumulative_field'}{'parameter_value'} =} != 0) and ({= @parameters{'session_id_field'}{'parameter_value'} =} ne '') and ({= @parameters{'session_id_field'}{'parameter_value'} =} ne '-')) then (

#echo('{= @parameters{'cumulative_field'}{'parameter_value'} =}: ' . {= @parameters{'cumulative_field'}{'parameter_value'} =} . '; {= @parameters{'session_id_field'}{'parameter_value'} =}=' . {= @parameters{'session_id_field'}{'parameter_value'} =} . '; @previous_value=' . @previous_value{{= @parameters{'session_id_field'}{'parameter_value'} =}});

  # If the current value is smaller than the previous value, this must be a client identifer (not a session identifier, with a new session; start over).
#  if ({= @parameters{'cumulative_field'}{'parameter_value'} =} < @previous_value{{= @parameters{'session_id_field'}{'parameter_value'} =}}) then
  if ({= @parameters{'cumulative_field'}{'parameter_value'} =} < get_collected_field({= @parameters{'session_id_field'}{'parameter_value'} =}, 'cfs_{= @parameters{'cumulative_field'}{'parameter_value'} =}')) then
    {= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =} = {= @parameters{'cumulative_field'}{'parameter_value'} =};

  # Subtract the previous event in this session from the current event, to get the value of the cumulative field for this event
  else
#    {= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =} = {= @parameters{'cumulative_field'}{'parameter_value'} =} - @previous_value{{= @parameters{'session_id_field'}{'parameter_value'} =}};
    {= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =} = {= @parameters{'cumulative_field'}{'parameter_value'} =} - get_collected_field({= @parameters{'session_id_field'}{'parameter_value'} =}, 'cfs_{= @parameters{'cumulative_field'}{'parameter_value'} =}');

  # Remember that this is the value for this session
#  @previous_value{{= @parameters{'session_id_field'}{'parameter_value'} =}} = {= @parameters{'cumulative_field'}{'parameter_value'} =};
  set_collected_field({= @parameters{'session_id_field'}{'parameter_value'} =}, 'cfs_{= @parameters{'cumulative_field'}{'parameter_value'} =}', {= @parameters{'cumulative_field'}{'parameter_value'} =});

); # if non-zero

`
  
        } # cumulative_field_sum_name
      } # filters
    } # add_sessions_database_filter

    # When attaching: Add the report field
    add_report_field = {
      type = "add_report_fields"
      fields = {      

        "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}" = {
          label = "{= @parameters{'cumulative_field_sum_name'}{'parameter_value'} =}"
          column_label = ""
          column_info = ""
          database_field = "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}"
          display_format_type = "{= @parameters{'display_format_type'}{'parameter_value'} =}"
          show_remainder_value = true
          show_average_value = true
          show_min_value = true
          show_max_value = true
          show_total_value = true
          percent_calculation = "sum"
        } # cumulative_field_sum_name

      } # fields
    } # add_report_field

    # When attaching: Add the report field to all xref groups
    add_xref_field = {
      type = "add_xref_fields"
      xref_group = "*"
      fields = {
        "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}" = ""
      } # fields
    } # add_xref_field

    # When attaching: Add the column to all report elements
    add_report_column = {
      type = "add_report_element_columns"
      report = "*"
      report_element = "*"
      columns = {

        "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}" = {
          report_field = "{= @parameters{'cumulative_field_sum_name'}{'final_node_name'} =}"
          show_column = true
          show_percent_column = false
          show_bar_column = false
          show_graph = false
        } # cumulative_field_sum_name

      } # columns
    } # add_report_columns

  } # attach_operations
  
} # cumulative_field_sum